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

  • Artigo
  • 14 minutos para o fim da leitura

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 as 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 globalmente em todas as distribuições instaladas em execução no WSL 2.
  • wsl.conf para definir configurações por distribuição para distribuições 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 em que o arquivo está armazenado, o escopo da configuração e a versão do WSL executando sua distribuição afetam todo o tipo de arquivo a ser escolhido.

A versão do WSL que você está executando afetará 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 Hyper-V ou VirtualBox).

wsl.conf

  • Armazenado no /etc diretório da distribuição como um arquivo unix.
  • Usado para definir as configurações por distribuição. As configurações configuradas 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 versão, WSL 1 ou WSL 2.
  • Para acessar o /etc diretório para uma distribuição instalada, use a linha de comando da distribuição para cd / acessar o diretório raiz e, em seguidals, listar arquivos ou explorer.exe . exibir no Windows Explorador de Arquivos. O caminho do diretório deve ser semelhante a: /etc/wsl.conf.

.wslconfig

  • Armazenado em seu %UserProfile% diretório.
  • 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 somente 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 elas não estão em execução como uma máquina virtual.
  • Para acessar seu %UserProfile% diretório, no PowerShell, use cd ~ para acessar seu diretório residencial (que normalmente é seu perfil C:\Users\<UserName>de usuário) ou você pode abrir o Windows Explorador de Arquivos 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.

Verifique qual versão do WSL você está executando.

Observação

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

A regra de 8 segundos

Você deve aguardar até que o subsistema que executa sua distribuição 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 depois de fechar TODAS as instâncias do shell de distribuição.

Se você iniciar uma distribuição (ou seja, Ubuntu), modifique o arquivo de configuração, feche a distribuição e inicie-o novamente. Você pode assumir 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 que o subsistema pare antes de relançar para dar tempo suficiente para que suas alterações sejam recolhidas. 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 suas 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 sabiamente.

Configurações para wsl.conf

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

O arquivo wsl.conf dá suporte a quatro seções: automount, network, e interopuser. (Modeladas após .ini convenções de arquivo, 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 sistemado

Muitas distribuições do Linux são executadas "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+ do WSL para habilitar o sistema. Verifique sua versão do WSL com o comando wsl --version. Se precisar atualizar, você poderá pegar a versão mais recente do WSL na Microsoft Store. Saiba mais no comunicado do blog.

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

[boot]
systemd=true

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

Configurações de desmontagem automática

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

chave value padrão HDInsight
Habilitado booleano true true faz com que as 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 pode montá-las manualmente ou via fstab.
mountFsTab booleano 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 para /mnt/c/. Se você mudar /mnt/ para /windir/, você deve esperar ver sua unidade C fixa montada para /windir/c.
opções Lista de valores separados por vírgulas, como uid, gid etc, veja as opções de desmontagem automática abaixo cadeia de caracteres vazia Os valores da opção de desmontagem automática são listados abaixo e são acrescentados à cadeia de opções de montagem padrão do DrvFs. Somente opções específicas do DrvFs podem ser especificadas.

As opções de desmontagem 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 /etc/fstab arquivo. 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 unidade para as quais deseja fazer isso /etc/fstab.

Opções de desmontagem 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, esse padrão é 1000)
gid A ID de grupo usada para o proprietário de todos os arquivos A ID de grupo padrão da distribuição do WSL (na primeira instalação, esse padrão é 1000)
umask Uma máscara octal de permissões a serem excluídas para todos os arquivos e diretórios 000
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 diferenciais de maiúsculas e minúsculas e se os novos diretórios criados com o WSL terão o sinalizador definido. Consulte a confidencialidade de maiúsculas e minúsculas para obter uma explicação detalhada das opções. As opções incluem off, dirou force. off

Por padrão, o WSL define o uid e o gid como o 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, 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, a máscara (arquivos) e a máscara (diretórios) também podem ser usadas.

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 são DrvFs?

O DrvFs é um plug-in do 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 confidencialidade de maiúsculas e minúsculas ao montar unidades ou diretórios do Windows ou Linux, consulte a página de confidencialidade de caso .

Configurações de rede

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

chave value padrão HDInsight
generateHosts booleano 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 booleano 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 WSL.

Configurações de interoperabilidade

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

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

chave value padrão HDInsight
Habilitado booleano true Definir essa chave determinará se o WSL dará suporte à inicialização de processos do Windows.
appendWindowsPath booleano 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: [user]

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

chave value padrão HDInsight
padrão string O nome de usuário inicial criado na primeira execução Definir essa chave especifica como o usuário deve ser executado quando iniciar uma sessão WSL pela primeira vez.

Configurações de inicialização

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

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

chave value padrão HDInsight
. 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 wsl.conf arquivo de exemplo 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 process 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

Configuração 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

As opções de configuração global com .wslconfig apenas estão disponíveis 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 sejam afetadas.

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

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

chave value padrão HDInsight
kernel string 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 ou 8 GB, o que for menor; em builds antes de 20175: 80% da memória total no Windows Quanta memória atribuir à VM WSL 2.
processadores número O mesmo número de processadores no Windows Quantos processadores atribuir à VM WSL 2.
localhostForwarding booleano true Boolean especificando se as portas associadas a caractere curinga ou localhost na VM WSL 2 devem ser conectáveis do host por meio localhost:portde .
kernelCommandLine string Em branco Argumentos de linha de comando adicionais do kernel.
swap tamanho 25% do tamanho da memória no Windows arredondado até o GB mais próximo Quanto espaço de troca adicionar à VM WSL 2, 0 para nenhum arquivo de troca. O armazenamento de troca é a RAM baseada em disco usada quando a demanda de memória excede o limite no dispositivo de hardware.
swapFile string %USERPROFILE%\AppData\Local\Temp\swap.vhdx Um caminho absoluto do Windows para o disco rígido virtual de troca.
pageReporting booleano true A configuração padrão true permite que o Windows recupere a memória não utilizado alocada para a máquina virtual WSL 2.
guiApplications Boolean* true Boolean para ativar ou desativar o suporte para aplicativos de GUI (WSLg) no WSL. Disponível somente para Windows 11.
debugConsole Boolean* false Boolean para ativar uma janela do console de saída que mostra o conteúdo do dmesg início de uma instância de distribuição do WSL 2. Disponível somente para Windows 11.
aninhadoVirtualization Boolean* true Boolean para ativar ou desativar a virtualização aninhada, permitindo que outras VMs aninhadas executem 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 desligada. Disponível somente para Windows 11.

As entradas com o path valor devem ser caminhos do Windows com backslashes escapados, por exemplo: C:\\Temp\\myCustomKernel

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

As entradas com um * após o tipo de valor só estão disponíveis em Windows 11.

Exemplo de arquivo .wslconfig

O .wslconfig arquivo de exemplo 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 off default connection to bind WSL 2 localhost to Windows localhost
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

Recursos adicionais