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

  • Artigo

Os arquivos wsl.conf e .wslconfig são usados para definir opções de configurações avançadas, por distribuição (wsl.conf) e globalmente em todas as distribuições do WSL 2 (.wslconfig). Este guia abordará cada uma das opções de configurações, quando usar cada tipo de arquivo, onde armazenar o arquivo, arquivos de configurações de exemplo e dicas.

Qual é a diferença entre wsl.conf e .wslconfig?

Você pode definir as configurações para suas distribuições do Linux instaladas que serão aplicadas automaticamente toda vez que você iniciar o WSL de duas maneiras, usando:

  • .wslconfig para definir as configurações globais em todas as distribuições instaladas em execução no WSL 2.
  • wsl.conf para definir as configurações locais por distribuição para cada distribuição do Linux em execução no WSL 1 ou WSL 2.

Ambos os tipos de arquivo são usados para definir as configurações do WSL, mas o local onde o arquivo é armazenado, o escopo da configuração, o tipo de opções que podem ser configuradas e a versão do WSL executando sua distribuição afetam o tipo de arquivo a ser escolhido.

O WSL 1 e o WSL 2 são executados com arquitetura diferente e afetarão as configurações. O WSL 2 é executado como uma VM (máquina virtual) leve, portanto, usa configurações de virtualização que permitem controlar a quantidade de memória ou processadores usados (o que pode ser familiar se você usar o Hyper-V ou o VirtualBox). 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 desativará 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 . 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. (Modeladas após as convenções de arquivo .ini, as chaves são declaradas em uma seção, como 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 o arquivo wsl.conf em um editor de texto usando sudo para permissões de administrador e adicione essas linhas ao /etc/wsl.conf:

[boot]
systemd=true

Em seguida, você precisará encerrar sua distribuição do WSL usando o wsl.exe --shutdown do 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 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 value default observações
Habilitado booleano true O true causa unidades fixas (por exemplo C:/ ou D:/) a ser montado automaticamente com DrvFs em /mnt. O false significa que as unidades não serão montadas automaticamente, mas você ainda poderá montá-las manualmente ou por meio do fstab.
mountFsTab boolean 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 string /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.
opções lista de valores separados por vírgulas, como uid, gid etc, confira opções de montagem automática abaixo cadeia de caracteres vazia 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:

Key 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 desabilitado
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 Diferenciar maiúsculas e minúsculas para obter uma explicação detalhada das opções. As opções incluem off, dir e 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.

A máscara de modo de criação de arquivo do usuário (umask) define a permissão para arquivos recém-criados. O padrão é 022, somente você pode gravar dados, mas qualquer pessoa pode ler dados. Os valores podem ser alterados para refletir diferentes configurações de permissão. Por exemplo, a umask=077 altera a permissão para ser completamente privada, nenhum outro usuário pode ler ou gravar dados. Para especificar ainda mais a permissão, fmask (arquivos) e dmask (diretórios) também podem ser usados.

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 value default observações
generateHosts boolean true O 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 boolean true O 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 string 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 value default observações
Habilitado boolean true Definir essa chave determinará se o WSL dará suporte à inicialização de processos do Windows.
appendWindowsPath boolean 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 value default observações
default string 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 value default observações
. string "" 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.

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 do usuário (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 value default observações
kernel caminho A caixa de entrada fornecida pelo kernel da Microsoft Um caminho absoluto do Windows para um kernel personalizado do Linux.
memória tamanho 50% da memória total no Windows Quanta memória atribuir à VM do WSL 2.
processadores number O mesmo número de processadores lógicos no Windows Quantos processadores lógicos atribuir à VM do WSL 2.
localhostForwarding boolean 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 string Em branco Argumentos adicionais de linha de comando do kernel.
safeMode boolean 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.
troca tamanho 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. O armazenamento de troca é uma RAM baseada em disco usada quando a demanda 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 boolean 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. Disponível somente para Windows 11.
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 bool true Aplicável somente a networkingMode = NAT. Booliano para informar o WSL para configurar o servidor DNS no Linux para o NAT no host. A configuração como false espelhará os servidores DNS do Windows para o Linux.
networkingMode** string NAT Se o valor for mirrored, isso liga o modo de rede espelhado. Cadeias de caracteres padrão ou não reconhecidas resultam na rede NAT.
firewall** bool 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** bool false Altera a forma como as solicitações DNS são feitas por proxy do WSL para o Windows
autoProxy* bool false Impõe o WSL para usar informações de proxy HTTP do Windows

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 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.

As entradas com um ** após o tipo de valor exigem o 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]

Nome da configuração Valor Padrão Observações
autoMemoryReclaim string desabilitado Libera automaticamente a memória armazenada em cache depois de detectar o uso de CPU ocioso. Defina como gradual para versão lenta e dropcache para a versão instantânea da memória armazenada em cache.
sparseVhd bool false Quando definido como true, qualquer VHD recém-criado será definido como esparso automaticamente.
useWindowsDnsCache** bool false Aplicável somente quando wsl2.dnsTunneling é definido como true. Quando essa opção é definida como false, as solicitações DNS em túnel do Linux ignorarão os nomes armazenados em cache no Windows para sempre colocar as solicitações no fio.
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.
initialAutoProxyTimeout* string 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** string 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êinerse conecte ao Host, ou que o Host se conecte ao Contêiner, por meio de um endereço IP atribuído ao Host. O endereço de loopback 127.0.0.1 sempre pode ser usado; essa 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 o 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

# 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