Configurazione delle impostazioni avanzate in WSL

  • Articolo

I file wsl.conf e wslconfig vengono usati per configurare le opzioni di impostazione avanzate, su base individuale (wsl.conf) e globale per tutte le distribuzioni WSL 2 (.wslconfig). Questa guida illustra tutte le opzioni di impostazione, quando usare ogni tipo di file, dove archiviare il file, i file di impostazione di esempio e i suggerimenti.

Qual è la differenza tra wsl.conf e .wslconfig?

È possibile configurare le impostazioni per le distribuzioni Linux installate, che verranno applicate automaticamente ogni volta che si avvia WSL, in due modi, usando:

  • .wslconfig per configurare le impostazioni globali in tutte le distribuzioni installate in esecuzione in WSL 2.
  • wsl.conf per configurare le impostazioni locali per distribuzione per ogni distribuzione Linux in esecuzione in WSL 1 o WSL 2.

Entrambi i tipi di file vengono usati per configurare le impostazioni WSL, ma il percorso in cui è archiviato il file, l'ambito della configurazione, il tipo di opzioni che è possibile configurare e la versione di WSL che esegue la distribuzione influiscono su quale tipo di file scegliere.

WSL 1 e WSL 2 vengono eseguiti con un'architettura diversa e influiscono sulle impostazioni di configurazione. WSL 2 viene eseguito come macchina virtuale leggera (VM), quindi usa impostazioni di virtualizzazione che consentono di controllare la quantità di memoria o di processori usati (che può essere familiare se si usa Hyper-V o VirtualBox). Controllare la versione di WSL in esecuzione.

8 seconda regola per le modifiche alla configurazione

Per visualizzare gli aggiornamenti delle impostazioni di configurazione, è necessario attendere che il sottosistema che esegue la distribuzione Linux si arresti completamente e si riavvii. Questa operazione richiede in genere circa 8 secondi dopo la chiusura di TUTTE le istanze della shell di distribuzione.

Se si avvia una distribuzione (ad esempio Ubuntu), si modifica il file di configurazione, si chiude la distribuzione e poi la si riavvia, si potrebbe pensare che le modifiche alla configurazione siano entrate immediatamente in vigore. Al momento non è così, perché il sottosistema potrebbe essere ancora in esecuzione. È necessario attendere che il sottosistema si arresti prima di riavviarlo, in modo da avere il tempo sufficiente per recepire le modifiche. È possibile verificare se la distribuzione Linux (shell) è ancora in esecuzione dopo la chiusura usando PowerShell con il comando: wsl --list --running. Se non ci sono distribuzioni in esecuzione, si riceverà la risposta: "Non ci sono distribuzioni in esecuzione". È ora possibile riavviare la distribuzione per vedere applicati gli aggiornamenti della configurazione.

Il comando wsl --shutdown è un metodo rapido per riavviare le distribuzioni WSL 2, ma arresta tutte le distribuzioni in esecuzione, quindi va usato con attenzione. È anche possibile usare wsl --terminate <distroName> per terminare immediatamente una distribuzione specifica in esecuzione.

wsl.conf

Configurare le impostazioni locali con wsl.conf per distribuzione per ogni distribuzione Linux in esecuzione in WSL 1 o WSL 2.

  • Archiviato nella directory /etc della distribuzione come file unix.
  • Usato per configurare le impostazioni per ogni distribuzione. Le impostazioni configurate in questo file saranno applicate solo alla distribuzione Linux specifica che contiene la directory in cui è archiviato il file.
  • Può essere usato per le distribuzioni eseguite da entrambe le versioni, WSL 1 o WSL 2.
  • Per accedere alla /etc directory di una distribuzione installata, usare la riga di comando della distribuzione con cd / per accedere alla directory radice, quindi ls per elencare i file o explorer.exe . per visualizzare in Esplora file di Windows. Il percorso della directory dovrebbe essere simile a: /etc/wsl.conf.

Nota

La regolazione delle impostazioni per distribuzione con il file wsl.conf è disponibile solo in Windows Build 17093 e successive.

Impostazioni di configurazione per wsl.conf

Il file wsl.conf configura le impostazioni in base alla distribuzione. (Per la configurazione globale delle distribuzioni WSL 2, vedere .wslconfig).

Il file wsl.conf supporta quattro sezioni: automount, network, interope user. (Sul modello delle convenzioni dei file .ini, le chiavi sono dichiarate in una sezione, ad esempio i file .gitconfig) Vedere wsl.conf per informazioni su dove archiviare il file wsl.conf.

supporto systemd

Molte distribuzioni Linux eseguono "systemd" per impostazione predefinita (incluso Ubuntu) e WSL ha recentemente aggiunto il supporto per questo system/service manager, in modo che WSL sia ancora più simile all'uso delle distribuzioni Linux preferite in un computer bare metal. Per abilitare systemd è necessaria la versione 0.67.6+ di WSL. Controllare la versione di WSL con il comando wsl --version. Se è necessario eseguire l’aggiornamento, è possibile ottenere la versione più recente di WSL in Microsoft Store. Per altre informazioni, vedere l'annuncio del blog.

Per abilitare systemd, aprire il file wsl.conf in un editor di testo usando sudo per le autorizzazioni di amministratore e aggiungere queste righe a /etc/wsl.conf:

[boot]
systemd=true

Sarà quindi necessario chiudere la distribuzione WSL usando wsl.exe --shutdown da PowerShell per riavviare le istanze WSL. Una volta riavviata la distribuzione, systemd dovrebbe essere in esecuzione. È possibile confermare usando il comando: systemctl list-unit-files --type=service, che mostrerà lo stato dei servizi.

Impostazioni di montaggio automatico

etichetta della sezione wsl.conf: [automount]

key value default note
Enabled boolean True true fa sì che le unità fisse (ad esempio C:/ o D:/) vengano montate automaticamente con DrvF in /mnt. false significa che le unità non verranno montate automaticamente, ma è comunque possibile montarle manualmente o tramite fstab.
mountFsTab boolean True true specifica che /etc/fstab venga elaborato all'avvio di Sottosistema Windows per Linux. /etc/fstab è un file in cui puoi dichiarare altri file system, ad esempio una condivisione SMB. In questo modo puoi montare questi file system automaticamente in Sottosistema Windows per Linux all'avvio.
root stringa /mnt/ Imposta la directory in cui verranno montate automaticamente le unità fisse. Per impostazione predefinita questa impostazione è impostata su /mnt/, quindi l'unità C del file system di Windows viene montata in /mnt/c/. Se si modifica /mnt/ in /windir/, si dovrebbe visualizzare l'unità C fissa montata in /windir/c.
Opzioni elenco di valori separati da una virgola, come uid, gid, ecc, vedere le opzioni di montaggio automatico di seguito stringa vuota I valori delle opzioni di montaggio automatico sono elencati di seguito e vengono aggiunti alla stringa delle opzioni di montaggio predefinite DrvFs. È possibile specificare solo opzioni specifiche di DrvFs.

Le opzioni di montaggio automatico vengono applicate come opzioni di montaggio per tutte le unità montate automaticamente. Per modificare le opzioni solo per un'unità specifica, usare invece il file /etc/fstab. Le opzioni che il file binario di montaggio analizza normalmente in un flag non sono supportate. Se si desidera specificare esplicitamente queste opzioni, è necessario includere tutte le unità per le quali si desidera farlo in /etc/fstab.

Opzioni di montaggio automatico

L'impostazione di opzioni di montaggio diverse per le unità Windows (DrvFs) consente di controllare la modalità di calcolo delle autorizzazioni per i file di Windows. Di seguito vengono illustrate le opzioni disponibili.

Chiave Descrizione Predefinito
uid ID utente usato per il proprietario di tutti i file L'ID utente predefinito della distribuzione WSL (alla prima installazione il valore predefinito è 1000)
gid ID gruppo usato per il proprietario di tutti i file L’ID gruppo predefinito della distribuzione WSL (alla prima installazione il valore predefinito è 1000)
umask Maschera ottale delle autorizzazioni da escludere per tutti i file e le directory 022
fmask Maschera ottale delle autorizzazioni da escludere per tutti i file 000
dmask Maschera ottale delle autorizzazioni da escludere per tutte le directory 000
metadata Indica se i metadati vengono aggiunti ai file di Windows per supportare le autorizzazioni del sistema Linux disabilitato
case Determina le directory trattate come sensibili alle maiuscole e alle minuscole e se le nuove directory create con WSL avranno il flag impostato. Per una spiegazione dettagliata delle opzioni, vedere distinzione tra maiuscole e minuscole. Le opzioni includono off, dir, o force. off

Per impostazione predefinita, WSL imposta uid e gid sul valore dell'utente predefinito. Ad esempio, in Ubuntu, l'utente predefinito è uid=1000, gid=1000. Se questo valore viene usato per specificare un'opzione gid o uid diversa, il valore predefinito dell'utente verrà sovrascritto. In caso contrario, il valore predefinito verrà sempre accodato.

La modalità della maschera di creazione del file utente (umask) imposta l’autorizzazione per i file appena creati. Il valore predefinito è 022. Solo l'utente può scrivere i dati, ma chiunque può leggerli. I valori possono essere modificati in modo da riflettere le diverse impostazioni dei permessi. Ad esempio, umask=077 modifica l'autorizzazione in modo che sia completamente privata, nessun altro utente potrà leggere o scrivere i dati. Per specificare ulteriormente l’autorizzazione, è anche possibile usare fmask (file) e dmask (directory).

Nota

le maschere delle autorizzazioni vengono sottoposte a un'operazione OR logica prima di essere applicate a file e directory.

Che cos'è DrvFs?

DrvFs è un plug-in per il filesystem di WSL, progettato per supportare l'interoperabilità tra WSL e il filesystem di Windows. DrvFs consente a WSL di montare le unità con i file system supportati in /mnt, come /mnt/c, /mnt/d, e così via. Per altre informazioni su come specificare il comportamento predefinito di distinzione tra maiuscole e minuscole durante il montaggio di unità o directory Windows o Linux, vedere la pagina sulla distinzione tra maiuscole e minuscole.

Impostazioni di rete

etichetta della sezione wsl.conf: [network]

key value default note
generateHosts boolean true true imposta Sottosistema Windows per Linux in modo da generare /etc/hosts. Il file hosts contiene una mappa statica di nomi host corrispondenti a un indirizzo IP.
generateResolvConf boolean true true imposta Sottosistema Windows per Linux in modo da generare /etc/resolv.conf. resolv.conf contiene un elenco DNS in grado di risolvere un determinato nome host nel relativo indirizzo IP.
hostname stringa Nome host di Windows Imposta il nome host da usare per la distribuzione di WSL.

Impostazioni di interoperabilità

etichetta della sezione wsl.conf: [interop]

Queste opzioni sono disponibili in Insider build 17713 e versioni successive.

key value default note
Enabled boolean true L'impostazione di questa chiave determinerà se Sottosistema Windows per Linux supporterà l'avvio dei processi di Windows.
appendWindowsPath boolean true L'impostazione di questa chiave determinerà se Sottosistema Windows per Linux aggiungerà gli elementi del percorso di Windows alla variabile di ambiente $PATH.

Impostazioni utente

etichetta della sezione wsl.conf: [user]

Queste opzioni sono disponibili nella build 18980 e versioni successive.

key value default note
default stringa Il nome utente iniziale creato alla prima esecuzione L'impostazione di questa chiave consente di specificare l'utente da usare al primo avvio di una sessione WSL.

Impostazioni di avvio

L'impostazione di avvio è disponibile solo in Windows 11 e Server 2022.

etichetta della sezione wsl.conf: [boot]

key value default note
Comando stringa "" Stringa del comando da eseguire all'avvio dell'istanza WSL. Questo comando viene eseguito come utente radice. ad esempio: service docker start.

File wsl.conf di esempio

Il file di esempio wsl.conf riportato di seguito mostra alcune delle opzioni di configurazione disponibili. In questo esempio, la distribuzione è Ubuntu-20.04 e il percorso del file è \\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

Configurare le impostazioni globali con .wslconfig in tutte le distribuzioni installate in esecuzione in WSL.

  • Il file con estensione wslconfig non esiste per impostazione predefinita. Deve essere creato e archiviato nella %UserProfile% directory per applicare queste impostazioni di configurazione.
  • Usato per configurare le impostazioni a livello globale in tutte le distribuzioni Linux installate in esecuzione come versione WSL 2.
  • Può essere usato solo per le distribuzioni eseguite da WSL 2. Le distribuzioni in esecuzione come WSL 1 non saranno interessate da questa configurazione, perché non sono in esecuzione come macchina virtuale.
  • Per accedere alla directory %UserProfile%, in PowerShell, usare cd ~ per accedere alla directory home (che in genere è il profilo utente, C:\Users\<UserName>) oppure è possibile aprire Esplora file di Windows e immettere %UserProfile% nella barra degli indirizzi. Il percorso della directory dovrebbe essere simile a: C:\Users\<UserName>\.wslconfig.

WSL rileverà l'esistenza di questi file, ne leggerà il contenuto e applicherà automaticamente le impostazioni di configurazione a ogni avvio di WSL. Se il file è mancante o non valido (formattazione non corretta del markup), WSL continuerà ad avviarsi normalmente senza applicare le impostazioni di configurazione.

Impostazioni di configurazione per .wslconfig

Il file .wslconfig configura le impostazioni a livello globale per tutte le distribuzioni Linux in esecuzione con WSL 2. (Per la configurazione per distribuzione, vedere wsl.conf).

Vedere .wslconfig per informazioni su dove archiviare il file .wslconfig.

Nota

La configurazione delle impostazioni globali con .wslconfig sono disponibili solo per le distribuzioni in esecuzione come WSL 2 in Windows Build 19041 e versioni successive. Tenere presente che potrebbe essere necessario eseguire wsl --shutdown per arrestare la macchina virtuale WSL 2 e quindi riavviare l'istanza WSL per rendere effettive queste modifiche.

Questo file può contenere le opzioni seguenti che influiscono sulla macchina virtuale che alimenta qualsiasi distribuzione di WSL 2:

Impostazioni principali di WSL

Etichetta della sezione .wslconfig: [wsl2]

key value default note
kernel path Il kernel compilato da Microsoft ha fornito la casella di posta in arrivo Percorso assoluto di Windows per un kernel Linux personalizzato.
memory size 50% della memoria totale in Windows Quanta memoria assegnare alla macchina virtuale WSL 2.
processori number Lo stesso numero di processori logici in Windows Numero di processori logici da assegnare alla macchina virtuale WSL 2.
localhostForwarding boolean true Valore booleano che specifica se le porte associate a caratteri jolly o localhost nella macchina virtuale WSL 2 devono essere collegate dall'host tramite localhost:port.
kernelCommandLine stringa Blank Argomenti aggiuntivi della riga di comando del kernel.
safeMode boolean false Eseguire WSL in "Modalità provvisoria", che disabilita molte funzionalità e deve essere usata per recuperare le distribuzioni in stato non valido. Disponibile solo per Windows 11 e WSL versione 0.66.2+.
scambio size 25% della dimensione della memoria in Windows, arrotondato al GB più vicino Quantità di spazio di scambio da aggiungere alla macchina virtuale WSL 2, 0 per nessun file di scambio. L’archiviazione di scambio è una RAM basata su disco usata quando la richiesta di memoria supera il limite del dispositivo hardware.
swapFile path %USERPROFILE%\AppData\Local\Temp\swap.vhdx Percorso assoluto di Windows per lo scambio del disco rigido virtuale.
pageReporting boolean true L'impostazione predefinita true consente a Windows di recuperare la memoria inutilizzata allocata alla macchina virtuale WSL 2.
guiApplications booleano* true Valore booleano per attivare o disattivare il supporto delle applicazioni GUI (WSLg) in WSL. Disponibile solo per Windows 11.
debugConsole booleano* false Valore booleano per attivare una finestra della console di output che mostra il contenuto di dmesg all'avvio di un'istanza di distribuzione WSL 2. Disponibile solo per Windows 11.
nestedVirtualization booleano* true Valore booleano per attivare o disattivare la virtualizzazione annidata, che consente l'esecuzione di altre macchine virtuali nidificate all'interno di WSL 2. Disponibile solo per Windows 11.
vmIdleTimeout numero* 60000 Numero di millisecondi in cui una macchina virtuale rimane inattiva prima dell’arresto. Disponibile solo per Windows 11.
dnsProxy bool true Applicabile solo a networkingMode = NAT. Valore booleano per informare WSL di configurare il server DNS in Linux per nat nell'host. L'impostazione su false eseguirà il mirroring dei server DNS da Windows a Linux.
networkingMode** string NAT Se il valore è mirrored, si attiva la modalità di rete con mirroring. Le stringhe predefinite o non riconosciute comportano una rete NAT.
Firewall** bool true Impostando questa proprietà su true, le regole del firewall di Windows e le regole specifiche del traffico Hyper-V possono filtrare il traffico di rete WSL.
dnsTunneling** bool False Modifica la modalità di proxy delle richieste DNS da WSL a Windows
autoProxy* bool False Applica l’uso da parte di WSL delle informazioni sul proxy HTTP di Windows

Le voci con il valore path devono essere percorsi di Windows con barre rovesciate di escape, ad esempio: C:\\Temp\\myCustomKernel

Le voci con il size valore devono essere una dimensione seguita da un'unità, ad esempio 8GB o 512MB.

Le voci con un * dopo il tipo di valore sono disponibili solo in Windows 11.

Le voci con ** dopo il tipo di valore richiedono Windows 11 versione 22H2 o successiva.

Impostazioni sperimentali

Queste impostazioni sono anteprime esplicite di funzionalità sperimentali che verranno rese predefinite in futuro.

Etichetta della sezione .wslconfig: [experimental]

Nome impostazione Valore Valore predefinito Note
autoMemoryReclaim stringa disabilitato Rilascia automaticamente la memoria cache dopo aver rilevato l'utilizzo inattivo della CPU. Impostare su gradual per il rilascio lento e dropcache per il rilascio immediato della memoria cache.
sparseVhd bool False Se impostato su true, qualsiasi disco rigido virtuale appena creato verrà impostato in modo automatico su sparse.
useWindowsDnsCache** bool False Si applica solo quando wsl2.dnsTunneling è impostato su true. Quando questa opzione è impostata su false, le richieste DNS con tunneling da Linux ignorano i nomi memorizzati nella cache all'interno di Windows per inserire sempre le richieste in rete.
bestEffortDnsParsing** bool False Si applica solo quando wsl2.dnsTunneling è impostato su true. Se impostato su true, Windows estrarrà la domanda dalla richiesta DNS e tenterà di risolverla, ignorando i record sconosciuti.
initialAutoProxyTimeout* stringa 1000 Si applica solo quando wsl2.autoProxy è impostato su true. Configura per quanto tempo (in millisecondi) WSL attenderà il recupero delle informazioni del proxy HTTP all'avvio di un contenitore WSL. Se le impostazioni proxy vengono risolte dopo questo periodo, sarà necessario riavviare l'istanza WSL per usare le impostazioni proxy recuperate.
ignoredPorts** stringa Null Si applica solo quando wsl2.networkingMode è impostato su mirrored. Specifica a quali porte si possono collegare le applicazioni Linux, anche se tale porta è usata in Windows. Ciò consente alle applicazioni di rimanere in ascolto su una porta per il traffico esclusivamente all'interno di Linux, quindi tali applicazioni non vengono bloccate anche quando tale porta viene usata per altri scopi in Windows. Ad esempio, WSL consentirà l'associazione alla porta 53 in Linux per Docker Desktop, perché è in ascolto solo delle richieste dall'interno del contenitore Linux. Deve essere formattato in un elenco delimitato da virgole, ad esempio: 3000,9000,9090
hostAddressLoopback** bool False Si applica solo quando wsl2.networkingMode è impostato su mirrored. Se impostato su True, consentirà al contenitore di connettersi all'host o all'host di connettersi al contenitore da un indirizzo IP assegnato all'host. L'indirizzo 127.0.0.1 di loopback può essere sempre usato, questa opzione consente anche l'uso di tutti gli indirizzi IP locali assegnati. Sono supportati solo gli indirizzi IPv4 assegnati all'host.

Le voci con un * dopo il tipo di valore sono disponibili solo in Windows 11.

Le voci con ** dopo il tipo di valore richiedono Windows versione 22H2 o successiva.

File di esempio .wslconfig

Il file di esempio .wslconfig riportato di seguito mostra alcune delle opzioni di configurazione disponibili. In questo esempio il percorso del file è 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

Risorse aggiuntive