Configuração avançada de definições 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 do WSL VM. wsl.conf é usado para aplicar configurações por distro WSL e .wslconfig é usado para aplicar configurações globais ao WSL. Você pode ler mais sobre as diferenças abaixo.

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

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

Você deve esperar até que o subsistema que executa sua distribuição Linux pare completamente de ser executado e reinicialize para que as atualizações de definições de configuração apareçam. Isso normalmente 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, em seguida, reiniciá-la, você pode assumir que suas alterações de configuração entraram imediatamente em vigor. Este não é o caso atualmente, pois o subsistema ainda pode estar em execução. Você deve esperar que o subsistema pare antes de reiniciar, a fim de dar tempo suficiente para que suas alterações sejam retiradas. Você pode verificar se sua distribuição Linux (shell) ainda está em execução depois de 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 distribuições WSL 2, mas ele desligará todas as distribuições em execução, portanto, use com sabedoria. Você também pode usar wsl --terminate <distroName> para encerrar uma distribuição específica que está sendo executada instantaneamente.

WSL.conf

Configure configurações locais com wsl.conf por distribuição para cada distribuição 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 configurações por distribuição. As configurações configuradas neste arquivo só serão aplicadas à distribuição Linux específica que contém o diretório onde esse arquivo está armazenado.
• Pode ser usado para distribuições executadas por qualquer versão, WSL 1 ou WSL 2.
• Para chegar ao 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 listar arquivos ou explorer.exe . exibir no Explorador de Arquivos do Windows. O caminho do diretório deve ser algo como: /etc/wsl.conf.

Definições de configuração para wsl.conf

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

O arquivo wsl.conf suporta quatro seções: automount, network, interope user. (Modeladas de acordo com .ini convenções de arquivos, 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 do systemd

Muitas distribuições Linux rodam "systemd" por padrão (incluindo o Ubuntu) e a WSL adicionou recentemente suporte para este sistema/gerenciador de serviços para que o WSL seja ainda mais semelhante ao uso de suas distribuições Linux favoritas em uma máquina bare metal. Você precisará da versão 0.67.6+ do WSL para habilitar o systemd. Verifique sua versão do WSL com o comando wsl --version. Se precisar de atualizar, pode obter a versão mais recente do WSL na Microsoft Store. Saiba mais no anúncio 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 estas linhas ao /etc/wsl.conf:

[boot]
systemd=true

Em seguida, você precisará fechar sua distribuição WSL usando wsl.exe --shutdown do PowerShell para reiniciar suas instâncias WSL. Assim 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 em wsl.conf: [automount]

As opções de montagem automática são utilizadas para todas as unidades montadas automaticamente. Para alterar as opções apenas para uma unidade específica, use o arquivo /etc/fstab. Opções que o binário de montagem normalmente analisaria em um sinalizador não são suportadas. Se você quiser especificar explicitamente essas opções, você deve incluir todas as unidades para as quais deseja fazê-lo em /etc/fstab.

Opções de montagem automática

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

Por padrão, o WSL define o uid e gid para 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 ou gid diferenteuid, 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 só se aplicarão quando a unidade do Windows estiver montada com metadados. Por padrão, os metadados não estão habilitados. Você pode encontrar mais informações sobre isso aqui.

O que é DrvFs?

DrvFs é um plugin de sistema de arquivos para WSL que foi projetado para suportar a interoperabilidade entre WSL e o sistema de arquivos do Windows. O DrvFs permite que o WSL monte unidades com sistemas de ficheiros suportados 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 Windows ou Linux, consulte a página de diferenciação de maiúsculas e minúsculas .

Configurações de rede

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

Configurações de interoperabilidade

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

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

Configurações do usuário

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

Essas opções estão disponíveis na compilação 18980 e posterior.

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 em wsl.conf: [boot]

Configurações da GPU

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

Configurações de tempo

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

Exemplo de arquivo wsl.conf

O arquivo de exemplo de 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

Configure 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 definições de configuração.
• Usado para definir configurações globalmente em todas as distribuições Linux instaladas rodando como a versão WSL 2.
• Pode ser usado apenas para distribuições executadas pelo WSL 2. As distribuições executadas como WSL 1 não serão afetadas por essa configuração, pois não estão sendo executadas como uma máquina virtual.
• Para acessar seu diretório %UserProfile%, no PowerShell, use cd ~ para acessar seu diretório base (que normalmente é seu perfil de usuário, C:\Users\<UserName>) ou você pode abrir o Explorador de Arquivos do Windows e inseri%UserProfile% na barra de endereço. O caminho do diretório deve ser algo como: C:\Users\<UserName>\.wslconfig.

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

Definições de configuração para .wslconfig

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

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

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

Principais configurações da WSL

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

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

Entradas com o size valor padrão para B (bytes), e a unidade é omissível. Para utilizar outras unidades, a unidade de tamanho deve ser anexada, por exemplo: 8GB ou 512MB.

¹: Disponível apenas no Windows 11.

²: Requer Windows 11 versão 22H2 ou superior.

Contextos experimentais

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

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

¹: Disponível apenas no Windows 11.

²: Requer Windows 11 versão 22H2 ou superior.

Exemplo de arquivo .wslconfig

O arquivo de exemplo de .wslconfig abaixo demonstra algumas das opções de configuração disponíveis. Neste exemplo, o caminho do arquivo é %UserProfile%\.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

# 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

# Sets the maximum number of crash dump files to retain (default is 5)
maxCrashDumpCount=10

# Enable experimental features
[experimental]
sparseVhd=true

Recursos adicionais

• Blog da linha de comando do Windows: Configurando automaticamente o WSL
• Blog da linha de comando do Windows: Chmod/Chown, DrvFs, metadados de arquivo