Configuration des paramètres avancés dans WSL

  • Article

Les fichiers wsl.conf et .wslconfig sont utilisés pour configurer les options de paramètres avancés, par distribution (wsl.conf) et globalement pour toutes les distributions WSL 2 (.wslconfig). Ce guide couvre chacune des options de paramètres, quand utiliser chaque type de fichier, où stocker le fichier, des exemples de fichiers de paramètres et des conseils.

Quelle est la différence entre wsl.conf et .wslconfig ?

Vous pouvez configurer les paramètres de vos distributions Linux installées qui seront automatiquement appliquées chaque fois que vous lancez WSL de deux manières, à l’aide de :

  • .wslconfig pour configurer paramètres globaux sur toutes les distributions installées exécutées sur WSL 2.
  • wsl.conf pour configurer paramètres locaux par distribution pour chaque distribution Linux exécutée sur WSL 1 ou WSL 2.

Les deux types de fichiers sont utilisés pour configurer les paramètres WSL, mais l’emplacement où le fichier est stocké, l’étendue de la configuration, le type d’options qui peuvent être configurées et la version de WSL exécutant votre distribution ont tous un impact sur le type de fichier à choisir.

WSL 1 et WSL 2 s’exécutent avec une architecture différente et affecteront les paramètres de configuration. WSL 2 s’exécute comme une machine virtuelle légère. Par conséquent, utilise des paramètres de virtualisation qui vous permettent de contrôler la quantité de mémoire ou de processeurs utilisés (ce qui peut être familier si vous utilisez Hyper-V ou VirtualBox). Vérifier la version de WSL que vous exécutez.

Règle de 8 secondes pour les modifications de configuration

Vous devez attendre que le sous-système exécutant votre distribution Linux cesse complètement de s’exécuter et redémarre pour que les mises à jour des paramètres de configuration apparaissent. Cela prend généralement environ 8 secondes après la fermeture de TOUTES les instances de l’interpréteur de commandes de distribution.

Si vous lancez une distribution (par exemple Ubuntu), modifiez le fichier de configuration, fermez la distribution, puis relancez-la, vous pouvez supposer que vos modifications de configuration sont immédiatement entrées en vigueur. Ce n’est pas le cas actuellement, car le sous-système est toujours en cours d’exécution. Vous devez attendre que le sous-système s’arrête avant de redémarrer afin de laisser suffisamment de temps pour que vos modifications soient récupérées. Vous pouvez case activée pour voir si votre distribution Linux (shell) est toujours en cours d’exécution après sa fermeture à l’aide de PowerShell avec la commande : wsl --list --running. Si aucune distribution n'est en cours d'exécution, vous recevrez la réponse : "Aucune distribution n'est en cours d'exécution." Vous pouvez maintenant redémarrer la distribution pour voir vos mises à jour de configuration appliquées.

La commande wsl --shutdown est un chemin d’accès rapide au redémarrage des distributions WSL 2, mais elle arrêtera toutes les distributions en cours d’exécution, donc utilisez judicieusement. Vous pouvez également utiliser wsl --terminate <distroName> pour terminer une distribution spécifique qui s’exécute instantanément.

wsl.conf

Configurez les paramètres locaux avec wsl.conf par distribution pour chaque distribution Linux exécutée sur WSL 1 ou WSL 2.

  • Stocké dans le répertoire /etc de la distribution sous la forme d’un fichier unix.
  • Utilisé pour configurer les paramètres par distribution. Les paramètres configurés dans ce fichier ne sont appliqués qu’à la distribution Linux spécifique qui contient le répertoire dans lequel ce fichier est stocké.
  • Peut être utilisé pour les distributions exécutées par une version, WSL 1 ou WSL 2.
  • Pour accéder au répertoire /etc d’une distribution installée, utilisez la ligne de commande de la distribution avec cd / pour accéder au répertoire racine, puis ls pour répertorier les fichiers ou explorer.exe . pour afficher dans Windows Explorateur de fichiers. Le chemin de répertoire doit être similaire à :/etc/wsl.conf.

Remarque

L’ajustement des paramètres par distribution avec le fichier wsl.conf est disponible uniquement dans Windows Build 17093 et versions ultérieures.

Paramètres de configuration pour wsl.conf

Le fichier wsl.conf configure les paramètres par distribution. (Pour la configuration globale des distributions WSL 2, consultez .wslconfig).

Le fichier wsl.conf prend en charge quatre sections : automount, network, interopet user. (Modélisées d'après les conventions des fichiers .ini, les clés sont déclarées dans une section, comme les fichiers .gitconfig.) Voir wsl.conf pour savoir où stocker le fichier wsl.conf.

prise en charge systemd

De nombreuses distributions Linux exécutent « systemd » par défaut (y compris Ubuntu) et WSL a récemment ajouté la prise en charge de ce gestionnaire de système/service afin que WSL soit encore plus similaire à l’utilisation de vos distributions Linux préférées sur une machine nue. Vous aurez besoin de la version 0.67.6+ de WSL pour activer systemd. Vérifiez votre version WSL avec la commande wsl --version. Si vous avez besoin de mettre à jour, vous pouvez récupérer la dernière version de WSL dans le Microsoft Store. Pour en savoir plus, consultez annonce de blog.

Pour activer systemd, ouvrez votre wsl.conf fichier dans un éditeur de texte à l’aide sudo des autorisations d’administrateur /etc/wsl.confet ajoutez ces lignes au :

[boot]
systemd=true

Vous devrez ensuite fermer votre distribution WSL à l’aide wsl.exe --shutdown de PowerShell pour redémarrer vos instances WSL. Une fois votre distribution redémarrée, systemd doit être en cours d’exécution. Vous pouvez confirmer à l’aide de la commande : systemctl list-unit-files --type=service, qui affiche l’état de vos services.

Paramètres de montage automatique

étiquette de section wsl.conf : [automount]

key value default Remarques
activé boolean true true fait en sorte que les lecteurs fixes (c.-à-d. C:/ ou D:/) soient automatiquement montés avec des DrvF sous /mnt. false : les disques ne sont pas montés automatiquement, mais vous pouvez les monter manuellement ou par le biais de fstab.
mountFsTab boolean true true : /etc/fstab est traité au démarrage de WSL. /etc/fstab est un fichier dans lequel vous pouvez déclarer d’autres systèmes de fichiers, comme un partage SMB. Ainsi, vous pouvez monter ces systèmes de fichiers automatiquement dans WSL au démarrage.
root string /mnt/ Définit le répertoire dans lequel les lecteurs fixes sont montés automatiquement. Par défaut, la valeur est définie sur /mnt/, de sorte que le lecteur C de votre système de fichiers Windows est monté sur /mnt/c/. Si vous passez /mnt/ à /windir/, vous devez vous attendre à voir votre lecteur C fixe monté sur /windir/c.
options Liste de valeurs séparées par des virgules, telles que uid, gid, etc. Consultez les options de montage automatique ci-dessous chaîne vide Les valeurs d’option de montage automatique sont répertoriées ci-dessous et sont ajoutées à la chaîne d’options de montage DrvFs par défaut. Seules les options propres à DrvFs peuvent être spécifiées.

Ces options de montage automatique sont appliquées en tant qu’options de montage pour tous les lecteurs montés automatiquement. Pour changer les options d’un lecteur spécifique uniquement, utilisez le fichier /etc/fstab à la place. Les options que le fichier binaire de montage analyse normalement dans un indicateur ne sont pas prises en charge. Si vous souhaitez spécifier explicitement ces options, vous devez inclure chaque lecteur pour lequel vous souhaitez le faire dans /etc/fstab.

Options de montage automatique

La définition des différentes options de montage pour les lecteurs Windows (DrvFs) peut contrôler la façon dont les autorisations de fichier sont calculées pour les fichiers Windows. Les options suivantes sont disponibles :

Clé Description Default
uid identifiant utilisateur utilisé pour le propriétaire de tous les fichiers identifiant utilisateur par défaut de votre distribution WSL (à la première installation, la valeur par défaut est 1000)
gid identifiant de groupe utilisé pour le propriétaire de tous les fichiers identifiant de groupe par défaut de votre distribution WSL (à la première installation, la valeur par défaut est 1000)
umask masque octal des autorisations à exclure pour tous les fichiers et répertoires 022
fmask masque octal des autorisations à exclure pour tous les fichiers 000
dmask masque octal des autorisations à exclure pour tous les répertoires 000
metadata Si des métadonnées sont ajoutées aux fichiers Windows pour prendre en charge les autorisations système Linux disabled
case Détermine les répertoires traités comme respectant la casse et si les nouveaux répertoires créés avec WSL auront l’indicateur défini. Consultez Respect de la casse pour obtenir une explication détaillée des options. Les options disponibles sont off, dir, ou force. off

Par défaut, le WSL fixe l'uid et le gid à la valeur de l'utilisateur par défaut. Par exemple, dans Ubuntu, l’utilisateur par défaut est uid=1000, gid=1000. Si cette valeur est utilisée pour spécifier une autre option gid ou uid, la valeur utilisateur par défaut est remplacée. Dans le cas contraire, la valeur par défaut est toujours ajoutée.

Le masque du mode de création de fichier utilisateur (umask) définit l’autorisation pour les fichiers nouvellement créés. La valeur par défaut est 022. Vous seul pouvez écrire des données, mais n’importe qui peut lire des données. Les valeurs peuvent être modifiées pour refléter différents paramètres d’autorisation. Par exemple, umask=077 modifie l’autorisation pour qu’elle soit entièrement privée, aucun autre utilisateur ne peut lire ou écrire des données. Pour spécifier davantage l’autorisation, fmask (fichiers) et dmask (répertoires) peuvent également être utilisés.

Remarque

Les masques d’autorisation passent par une opération OR logique avant d’être appliqués aux fichiers et aux répertoires.

Qu’est-ce que DrvFs ?

DrvFs est un plug-in de système de fichiers pour WSL qui a été conçu pour prendre en charge l’interopérabilité entre WSL et le système de fichiers Windows. DrvFs permet à WSL de monter des lecteurs avec des systèmes de fichiers pris en charge sous /mnt, tels que /mnt/c, /mnt/d, etc. Pour plus d'informations sur la spécification du comportement de sensibilité à la casse par défaut lors du montage de lecteurs ou de répertoires Windows ou Linux, consultez la page sur la sensibilité à la casse.

Paramètres réseau

étiquette de section wsl.conf : [network]

key value default Remarques
generateHosts boolean true true : WSL génère /etc/hosts. Le fichier hosts contient une carte statique de noms d’hôtes correspondant à l’adresse IP.
generateResolvConf booléen true true : WSL génère /etc/resolv.conf. resolv.conf contient une liste de noms DNS capables de résoudre un nom d’hôte donné en son adresse IP.
hostname string Nom d’hôte Windows Définit le nom d’hôte à utiliser pour la distribution WSL.

Paramètres d’interopérabilité

étiquette de section wsl.conf : [interop]

Ces options sont disponibles dans Insider build 17713 et ultérieures.

key value default Remarques
activé boolean true La définition de cette clé permet de déterminer si WSL prend en charge le lancement des processus Windows.
appendWindowsPath boolean true La définition de cette clé détermine si WSL ajoute des éléments de chemin Windows à la variable d’environnement $PATH.

Paramètres utilisateur

étiquette de section wsl.conf : [user]

Ces options sont disponibles dans build 18980 et ultérieures.

key value default Remarques
default string Nom d’utilisateur initial créé lors de la première exécution La définition de cette clé spécifie l’utilisateur sous lequel s’exécuter lors du premier démarrage d’une session WSL.

Paramètres de démarrage

Le paramètre de démarrage est disponible uniquement sur Windows 11 et Server 2022.

étiquette de section wsl.conf : [boot]

key value default Remarques
commande string "" Chaîne de la commande que vous souhaitez exécuter au démarrage de la instance WSL. Cette commande est exécutée en tant qu’utilisateur racine. Par exemple : service docker start.

Exemple de fichier wsl.conf

L’exemple wsl.conf de fichier ci-dessous illustre certaines des options de configuration disponibles. Dans cet exemple, la distribution est Ubuntu-20.04 et le chemin du fichier est \\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

Configurez les paramètres globaux avec .wslconfig sur toutes les distributions installées exécutées sur WSL.

  • Le fichier .wslconfig n’existe pas par défaut. Il doit être créé et stocké dans votre répertoire %UserProfile% pour appliquer ces paramètres de configuration.
  • Permet de configurer les paramètres globalement sur toutes les distributions Linux installées s’exécutant en tant que version WSL 2.
  • Peut être utilisé uniquement pour les distributions exécutées par WSL 2. Les distributions exécutées en tant que WSL 1 ne seront pas affectées par cette configuration, car elles ne s’exécutent pas en tant que machine virtuelle.
  • Pour accéder à votre répertoire%UserProfile%, dans PowerShell, utilisez cd ~ pour accéder à votre répertoire de base (qui est généralement votre profil utilisateur), C:\Users\<UserName>ou vous pouvez ouvrir Windows Explorateur de fichiers et entrer %UserProfile% dans la barre d’adresses. Le chemin de répertoire doit être similaire à :C:\Users\<UserName>\.wslconfig.

WSL détecte l’existence de ces fichiers, lit le contenu et applique automatiquement les paramètres de configuration chaque fois que vous lancez WSL. Si le fichier est manquant ou mal formé (mise en forme incorrecte du balisage), WSL continue de se lancer comme d’habitude sans que les paramètres de configuration ne s’appliquent.

Paramètres de configuration pour .wslconfig

Le fichier .wslconfig configure les paramètres globalement pour toutes les distributions Linux s’exécutant avec WSL 2. (Pour la configuration par distribution, consultez wsl.conf).

Consultez .wslconfig pour plus d’informations sur l’emplacement de stockage du fichier .wslconfig.

Remarque

La configuration des paramètres globaux avec .wslconfig est disponible uniquement pour les distributions exécutées en tant que WSL 2 dans Windows Build 19041 et versions ultérieures. N’oubliez pas que vous devrez peut-être exécuter wsl --shutdown pour arrêter la machine virtuelle WSL 2, puis redémarrer votre instance WSL pour que ces modifications prennent effet.

Ce fichier peut contenir les options suivantes qui affectent la machine virtuelle qui alimente toute distribution WSL 2 :

Principaux paramètres WSL

Étiquette de section .wslconfig : [wsl2]

key value default Remarques
noyau path Boîte de réception fournie par le noyau intégré Microsoft Chemin d’accès Windows absolu à un noyau Linux personnalisé.
memory size 50 % de la mémoire totale sur Windows Quantité de mémoire à affecter à la machine virtuelle WSL 2.
processeurs number Le même nombre de processeurs logiques sur Windows Nombre de processeurs logiques à affecter à la machine virtuelle WSL 2.
localhostForwarding boolean true Boolean spécifiant si les ports liés à un hôte générique ou local dans la machine virtuelle WSL 2 doivent être connectables à partir de l’hôte via localhost:port.
kernelCommandLine string Vide Arguments de ligne de commande supplémentaires du noyau.
safeMode boolean false Exécutez WSL en « mode sans échec » qui désactive de nombreuses fonctionnalités et est destiné à être utilisé pour récupérer des distributions qui sont dans des états incorrects. Disponible uniquement pour Windows 11 et WSL version 0.66.2+.
swap size 25 % de la taille de la mémoire sur Windows arrondie au Go le plus proche Espace d’échange à ajouter à la machine virtuelle WSL 2, 0 pour aucun fichier d’échange. Le stockage d’échange est une RAM sur disque utilisée lorsque la demande de mémoire dépasse la limite de l’appareil matériel.
swapFile path %USERPROFILE%\AppData\Local\Temp\swap.vhdx Chemin d’accès Windows absolu au disque dur virtuel d’échange.
pageReporting boolean true Le paramètre par défaut true permet à Windows de récupérer la mémoire inutilisée allouée à la machine virtuelle WSL 2.
guiApplications booléen* true Boolean pour activer ou désactiver la prise en charge des applications graphiques (WSLg) dans WSL. Disponible uniquement pour Windows 11.
debugConsole booléen* false Booléen pour activer une fenêtre de console de sortie qui affiche le contenu d’une dmesg distribution WSL 2 instance au démarrage. Disponible uniquement pour Windows 11.
nestedVirtualization booléen* true Booléen pour activer ou désactiver la virtualisation imbriquée, ce qui permet à d’autres machines virtuelles imbriquées de s’exécuter dans WSL 2. Disponible uniquement pour Windows 11.
vmIdleTimeout numéro* 60000 Nombre de millisecondes d’inactivité d’une machine virtuelle avant son arrêt. Disponible uniquement pour Windows 11.
dnsProxy bool true Applicable seulement à networkingMode = NAT. Boolean pour informer WSL de configurer le serveur DNS dans Linux sur la NAT sur l’hôte. Le fait de définir sa valeur sur false va reproduire les serveurs DNS de Windows vers Linux.
networkingMode** string NAT Si la valeur est mirrored, cela active le mode réseau en miroir. Les chaînes par défaut ou non reconnues entraînent une mise en réseau NAT.
pare-feu** bool true Définir cette valeur sur true permet aux règles du pare-feu Windows, ainsi qu'aux règles spécifiques au trafic Hyper-V, de filtrer le trafic réseau WSL.
dnsTunneling** bool false Modifie la façon dont les requêtes DNS sont transmises par proxy de WSL vers Windows
autoProxy* bool false Force WSL à utiliser les informations du proxy HTTP de Windows

Les entrées avec la valeur path doivent être des chemins Windows avec des barres obliques inverses d’échappement, par exemple : C:\\Temp\\myCustomKernel

Les entrées avec la valeur size doivent être une taille suivie d’une unité, par exemple, 8GB ou 512MB.

Les entrées avec un * après le type valeur ne sont disponibles que sur Windows 11.

Les entrées marquées avec ** après le type de valeur nécessitent Windows 11 version 22H2 ou ultérieure.

Paramètres expérimentaux

Ces paramètres sont des aperçus facultatifs des fonctionnalités expérimentales que nous souhaitons définir par défaut à l'avenir.

Étiquette de section .wslconfig : [experimental]

Nom du paramètre Valeur Par défaut Notes
autoMemoryReclaim string disabled Libère automatiquement la mémoire cache après avoir détecté une utilisation inactive du processeur. Réglé sur gradual pour une libération lente et dropcache pour une libération instantanée de la mémoire cache.
sparseVhd bool false Lorsqu'il est défini sur true, tout VHD nouvellement créé sera configuré automatiquement pour être clairsemé.
useWindowsDnsCache** bool false Applicable uniquement lorsque wsl2.dnsTunneling est défini sur true. Lorsque cette option a la valeur false, les requêtes DNS par tunnel à partir de Linux contournent les noms mis en cache dans Windows pour toujours placer les requêtes sur le réseau.
bestEffortDnsParsing** bool false Applicable uniquement lorsque wsl2.dnsTunneling est défini sur true. Lorsqu'il est défini sur true, Windows extraira la question de la requête DNS et tentera de la résoudre, en ignorant les enregistrements inconnus.
initialAutoProxyTimeout* string 1000 Applicable uniquement lorsque wsl2.autoProxy est défini sur true. Configure la durée (en millisecondes) de WSL pour récupérer les informations du proxy HTTP lors du démarrage d’un conteneur WSL. Si les paramètres de proxy sont résolus après ce délai, l'instance WSL doit être redémarrée pour utiliser les paramètres de proxy récupérés.
ignoredPorts** string null Applicable uniquement lorsque wsl2.networkingMode est défini sur mirrored. Spécifie les ports auxquels les applications Linux peuvent se lier, même si ce port est utilisé sous Windows. Cela permet aux applications d’écouter sur un port pour le trafic uniquement dans Linux, de sorte que ces applications ne sont pas bloquées même si ce port est utilisé à d’autres fins sur Windows. Par exemple, WSL autorise la liaison au port 53 dans Linux pour Docker Desktop, car il écoute uniquement les requêtes à partir du conteneur Linux. Doit être mis en forme dans une liste séparée par des virgules, par exemple : 3000,9000,9090
hostAddressLoopback** bool false Applicable uniquement lorsque wsl2.networkingMode est défini sur mirrored. Lorsque défini sur True, permettra au conteneur de se connecter à l'hôte, ou à l'hôte de se connecter au conteneur, par une adresse IP attribuée à l'hôte. Notez que l'adresse de bouclage 127.0.0.1 peut toujours être utilisée ; cette option permet d'utiliser également toutes les adresses IP locales attribuées en plus. Seules les adresses IPv4 attribuées à l’hôte sont prises en charge.

Les entrées avec un * après le type valeur ne sont disponibles que sur Windows 11.

Les entrées avec un ** après le type valeur nécessitent Windows version 22H2 ou ultérieure.

Exemple de fichier .wslconfig

L’exemple .wslconfig de fichier ci-dessous illustre certaines des options de configuration disponibles. Dans cet exemple, le chemin du fichier est 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

Ressources supplémentaires