Configuración avanzada en WSL

Los archivos wsl.conf y .wslconfig se usan para configurar opciones avanzadas en WSL que se aplicarán al iniciar la máquina virtual de WSL. wsl.conf se usa para aplicar la configuración según la distribución de WSL y se usa .wslconfig para aplicar la configuración global a WSL. Puede leer más sobre las diferencias siguientes.

Aspecto	.wslconfig	wsl.conf
Alcance	Configuración general que se aplica a todo WSL	Configuración solo para distribuciones de WSL
Configura	Habilitación de características en WSL, configuración de la máquina virtual que alimenta WSL 2 (RAM, kernel para arrancar, número de CPU, etc.)	Configuración de distribución en WSL, como las opciones de arranque, los automontajes de DrvFs, la configuración de red, la interoperabilidad con el sistema Windows, el uso de systemd y el usuario predeterminado
Ubicación	%UserProfile%\.wslconfig, fuera de una distribución de WSL	/etc/wsl.conf, dentro de una distribución de WSL

Actualmente, todas las configuraciones de .wslconfig solo se aplican a las distribuciones de WSL 2. Más información sobre cómo comprobar la versión de WSL que se está ejecutando.

La regla de los 8 segundos para los cambios de configuración

Debe esperar hasta que el subsistema que ejecuta la distribución de Linux deje de ejecutarse por completo y se reinicie para que aparezcan las actualizaciones de configuración. Normalmente, esto tarda unos 8 segundos después de cerrar TODAS las instancias del shell de distribución.

Si inicia una distribución (por ejemplo, Ubuntu), modifca el archivo de configuración, cierra la distribución y vuelve a iniciarla, puede pensar que los cambios de configuración han entrado inmediatamente en vigor. Este no es el caso actualmente, ya que el subsistema todavía podría estar en ejecución. Debe esperar a que el subsistema se detenga antes de volver a iniciarlo para dar tiempo suficiente para que se implementen los cambios. Puede comprobar si la distribución de Linux (shell) sigue ejecutándose después de cerrarla usando PowerShell con el comando: wsl --list --running. Si no se está ejecutando ninguna distribución, recibirá la respuesta: "No hay distribuciones en ejecución". Ahora puede reiniciar la distribución para ver las actualizaciones de configuración aplicadas.

El comando wsl --shutdown es una forma rápida de reiniciar las distribuciones de WSL 2, pero cerrará todas las distribuciones en ejecución, así que úselo con prudencia. También puede usar wsl --terminate <distroName> para finalizar de inmediato una distribución específica que se está ejecutando.

wsl.conf

Configure las opciones locales con wsl.conf por distribución para cada distribución de Linux que se ejecute en WSL 1 o WSL 2.

• Almacenado en el directorio /etc de la distribución como un archivo unix.
• Se usa para configurar las opciones por distribución. La configuración establecida en este archivo solo se aplicará a la distribución específica de Linux que contiene el directorio donde se almacena este archivo.
• Se puede usar para distribuciones que funcionan con cualquiera de las versiones, WSL 1 o WSL 2.
• Para llegar al directorio de /etc de una distribución instalada, use la línea de comandos de la distribución con cd / para acceder al directorio raíz, después ls para enumerar los archivos o explorer.exe . para verlos en el Explorador de archivos de Windows. La ruta de acceso debería tener un aspecto similar a: /etc/wsl.conf.

Nota:

El ajuste de la configuración por distribución con el archivo wsl.conf solo está disponible en la compilación 17093 de Windows y versiones posteriores.

Opciones de configuración para wsl.conf

El archivo wsl.conf configura los valores por distribución. (Para obtener la configuración global de las distribuciones de WSL 2, consulte .wslconfig).

El archivo wsl.conf admite cuatro secciones: automount, network, interop y user. (Modelado después de convenciones de archivo .ini, las claves se declaran en una sección, como los archivos .gitconfig). Consulte wsl.conf para obtener información sobre dónde almacenar el archivo wsl.conf.

compatibilidad con systemd

Muchas distribuciones de Linux ejecutan "systemd" de forma predeterminada (incluido Ubuntu) y WSL ha agregado recientemente compatibilidad con este administrador de servicios o sistema para que WSL sea aún más similar al uso de sus distribuciones de Linux favoritas en una máquina sin sistema operativo. Necesitará la versión 0.67.6+ de WSL para habilitar el sistema. Comprueba tu versión de WSL con el comando wsl --version. Si necesita actualizar, puede obtener la versión más reciente de WSL en la Tienda de Microsoft. Obtenga más información en el anuncio del blog.

Para habilitar systemd, abra su archivo wsl.conf en un editor de texto utilizando sudo para permisos de administrador y agregue estas líneas al /etc/wsl.conf:

[boot]
systemd=true

Después tendrá que cerrar su distribución de WSL usando wsl.exe --shutdown de PowerShell para reiniciar sus instancias de WSL. Una vez reiniciada la distribución, systemd debería estar en ejecución. Puede confirmar con el comando: systemctl list-unit-files --type=service, que mostrará el estado de sus servicios.

Configuración de montaje automático

Etiqueta de la sección wsl.conf: [automount]

clave	valor	default	notas
enabled	booleano	true	true hace que las unidades fijas (es decir, C:/ o D:/) se monten automáticamente con DrvFs bajo /mnt. false significa que las unidades no se montarán automáticamente, pero podría montarlas de forma manual o a través de fstab.
mountFsTab	booleano	true	true establece /etc/fstab para que se procese al iniciar WSL. /etc/fstab es un archivo donde puedes declarar otros sistemas de archivos, como un recurso compartido de SMB. Por lo tanto, puedes montar estos sistemas de archivos automáticamente en WSL en el inicio.
root	cadena	/mnt/	Establece el directorio donde se montarán automáticamente las unidades fijas. De manera predeterminada, esto se establece en /mnt/, por lo que la unidad C del sistema de archivos de Windows se monta en /mnt/c/. Si cambia /mnt/ a /windir/, debería esperar ver la unidad C fija montada en /windir/c.
options	Lista separada por comas de valores, como uid, gid, etc., consulte las opciones de montaje automático a continuación.	cadena vacía	Los valores de opción de montaje automático se enumeran a continuación y se anexan a la cadena de opciones de montaje de DrvFs predeterminada. Solo se pueden especificar opciones específicas de DrvFs.

Estas opciones de montaje automático se aplican como opciones de montaje para todas las unidades montadas automáticamente. Para cambiar las opciones solo para una unidad específica, use en su lugar el archivo /etc/fstab. No se admiten las opciones que el binario de montaje analizaría normalmente en una marca. Si quiere especificar explícitamente esas opciones, tiene que incluir en /etc/fstab cada unidad para la que quiera hacerlo.

Opciones de montaje automático

Establecer diferentes opciones de montaje para las unidades de Windows (DrvFs) puede controlar cómo se calculan los permisos de archivo para los archivos de Windows. Las siguientes opciones están disponibles:

Clave	Descripción	Valor predeterminado
uid	Id. de usuario que se usa para el propietario de todos los archivos	Id. de usuario predeterminado de su distribución WSL (en la primera instalación, el valor predeterminado es 1000)
gid	Id. de grupo que se usa para el propietario de todos los archivos	Id. de grupo predeterminado de su distribución WSL (en la primera instalación, el valor predeterminado es 1000)
umask	Máscara octal de permisos que se van a excluir para todos los archivos y directorios	022
fmask	Máscara octal de permisos que se van a excluir para todos los archivos	000
dmask	Máscara octal de permisos que se van a excluir para todos los directorios	000
metadata	Indica si se agregan metadatos a archivos de Windows para admitir permisos del sistema Linux	disabled
case	Determina los directorios tratados como sensibles a mayúsculas y minúsculas y si los nuevos directorios creados con WSL tendrán la marca establecida. Consulte distinción entre mayúsculas y minúsculas para obtener una explicación detallada de las opciones. Las opciones incluyen off, dir o force.	off

De manera predeterminada, WSL establece el uid y el gid en el valor del usuario predeterminado. Por ejemplo, en Ubuntu, el usuario predeterminado es uid=1000, gid=1000. Si este valor se usa para especificar una opción gid o uid diferente, se sobrescribirá el valor de usuario predeterminado. De lo contrario, siempre se anexará el valor predeterminado.

Máscara del modo de creación de archivos de usuario (umask) establece el permiso para los archivos recién creados. El valor predeterminado es 022, solo puede escribir datos, pero cualquier usuario puede leer datos. Los valores se pueden cambiar para reflejar diferentes configuraciones de permisos. Por ejemplo, umask=077 cambia el permiso para que sea completamente privado; ningún otro usuario puede leer ni escribir datos. Para especificar más permisos, también se pueden usar fmask (archivos) y dmask (directorios).

Nota:

Las máscaras de permisos se colocan a través de una operación OR lógica antes de aplicarse a archivos o directorios.

¿Qué es DrvFs?

DrvFs es un complemento del sistema de archivos a WSL diseñado para admitir la interoperabilidad entre WSL y el sistema de archivos de Windows. DrvFs permite que WSL monte unidades con sistemas de archivos compatibles en /mnt, como /mnt/c, /mnt/d, etc. Para más información sobre cómo especificar el comportamiento predeterminado de distinción entre mayúsculas y minúsculas al montar unidades o directorios de Windows o Linux, consulte la página de distinción entre mayúsculas y minúsculas.

Configuración de red

Etiqueta de sección de wsl.conf: [network]

clave	valor	default	notas
generateHosts	booleano	true	true configura WSL para generar /etc/hosts. El archivo hosts contiene una asignación estática de direcciones IP correspondientes a nombres de host.
generateResolvConf	booleano	true	true configura WSL para generar /etc/resolv.conf. resolv.conf contiene una lista de DNS que es capaz de resolver un nombre de host determinado en su dirección IP.
hostname	cadena	Nombre de host de Windows	Establece el nombre de host que se usará para la distribución de WSL.

Configuración de interoperabilidad

Etiqueta de la sección wsl.conf: [interop]

Estas opciones están disponibles en la compilación 17713 de Insider y versiones posteriores.

clave	valor	default	notas
enabled	booleano	true	La configuración de esta clave determinará si WSL admitirá el inicio de procesos de Windows.
appendWindowsPath	booleano	true	Establecer esta clave determinará si WSL agregará elementos de la ruta de Windows a la variable de entorno $PATH.

Configuración de usuario

Etiqueta de sección de wsl.conf: [user]

Estas opciones están disponibles en la compilación 18980 y versiones posteriores.

clave	valor	default	notas
default	cadena	Nombre de usuario inicial creado en la primera ejecución	Al establecer esta clave se especifica el usuario con el que se ejecutará cuando se inicie por primera vez una sesión de WSL.

Configuración de arranque

La configuración de arranque solo está disponible en Windows 11 y Server 2022.

Etiqueta de sección de wsl.conf: [boot]

clave	valor	default	notas
command	cadena	""	Cadena del comando que desea ejecutar cuando se inicia la instancia de WSL. Este comando se ejecuta como el usuario raíz. Por ejemplo, service docker start.

Archivo wsl.conf de ejemplo

El archivo de muestra a continuación demuestra algunas de las opciones de configuración disponibles. En este ejemplo, la distribución es Ubuntu-20.04 y la ruta de acceso del archivo es \\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

Configura opciones globales con .wslconfig en todas las distribuciones instaladas que se ejecutan en WSL.

• El archivo .wslconfig no existe de manera predeterminada. Debe crearse y almacenarse en su %UserProfile% directorio para aplicar estos ajustes de configuración.
• Se usa para configurar las opciones globalmente en todas las distribuciones de Linux instaladas que se ejecutan como la versión WSL 2.
• Solo puede utilizarse para distribuciones ejecutadas por WSL 2. Las distribuciones que se ejecutan como WSL 1 no se verán afectadas por esta configuración, ya que no se ejecutan como una máquina virtual.
• Para llegar a tu directorio %UserProfile%, en PowerShell, usa cd ~ para acceder a tu directorio principal (que suele ser tu perfil de usuario, C:\Users\<UserName>), o puedes abrir el Explorador de archivos de Windows y escribir %UserProfile% en la barra de direcciones. La ruta de acceso debe tener un aspecto similar a: C:\Users\<UserName>\.wslconfig.

WSL detectará la existencia de estos archivos, leerá el contenido y aplicará automáticamente las opciones de configuración cada vez que inicie WSL. Si falta el archivo o tiene un formato incorrecto (formato de marcado incorrecto), WSL seguirá iniciándose de forma normal sin aplicar las opciones de configuración.

Opciones de configuración para .wslconfig

El archivo .wslconfig configura las opciones globalmente para todas las distribuciones de Linux que se ejecutan con WSL 2. (Para la configuración por distribución, consulte wsl.conf).

Consulte .wslconfig para obtener información sobre dónde almacenar el archivo .wslconfig.

Nota:

La configuración de las opciones globales con .wslconfig solo está disponible para las distribuciones que se ejecutan como WSL 2 en la compilación 19041 de Windows y en versiones posteriores. Tenga en cuenta que es posible que tenga que ejecutar wsl --shutdown para apagar la máquina virtual WSL 2 y, después, reiniciar la instancia de WSL para que estos cambios surtan efecto.

Este archivo puede contener las siguientes opciones que afectan a la máquina virtual que alimenta cualquier distribución de WSL 2:

Configuración principal de WSL

Etiqueta de sección de .wslconfig: [wsl2]

clave	valor	default	notas
kernel	camino	Bandeja de entrada proporcionada por el kernel compilado de Microsoft	Ruta de acceso absoluta de Windows a un kernel de Linux personalizado.
kernelModules	camino	Ruta de acceso absoluta de Windows a un disco duro virtual de los módulos de kernel de Linux personalizado.
memory	size	50 % de memoria total en Windows	Cantidad de memoria que se va a asignar a la máquina virtual WSL 2.
processors	number	El mismo número de procesadores lógicos en Windows	Número de procesadores lógicos que se van a asignar a la máquina virtual de WSL 2.
localhostForwarding	booleano	true	Booleano que especifica si los puertos vinculados a comodín o localhost en la máquina virtual de WSL 2 deben poder conectarse desde el host a través de localhost:port.
kernelCommandLine	cadena	En blanco	Argumentos adicionales de la línea de comandos del kernel.
safeMode	booleano	false	Ejecute WSL en "Modo seguro", que deshabilita muchas características y está pensada para usarse para recuperar distribuciones que están en estados incorrectos. Solo está disponible para Windows 11 y WSL versión 0.66.2 y versiones posteriores.
swap	size	25 % del tamaño de memoria en Windows redondeado a los GB más cercanos	Cantidad de espacio de intercambio que se va a agregar a la VM de WSL 2, 0 para no crear un archivo de intercambio. El almacenamiento de intercambio es la RAM basada en disco que se usa cuando la demanda de memoria supera el límite en el dispositivo de hardware.
swapFile	camino	%USERPROFILE%\AppData\Local\Temp\swap.vhdx	Ruta de acceso absoluta de Windows al disco duro virtual de intercambio.
pageReporting	booleano	true	La configuración predeterminada true permite a Windows reclamar la memoria no utilizada asignada a la máquina virtual de WSL 2.
guiApplications	booleano	true	Booleano para activar o desactivar la compatibilidad con aplicaciones GUI (WSLg) en WSL.
debugConsole*	booleano	false	Booleano para activar una ventana de consola de salida que muestra el contenido de dmesg al inicio de una instancia de distribución de WSL 2. Solo está disponible para Windows 11.
nestedVirtualization*	booleano	true	Booleano para activar o desactivar la virtualización anidada, lo que permite que otras máquinas virtuales anidadas se ejecuten dentro de WSL 2. Solo está disponible para Windows 11.
vmIdleTimeout*	number	60000	Número de milisegundos que una máquina virtual está inactiva, antes de apagarla. Solo está disponible para Windows 11.
dnsProxy	booleano	true	Solo aplicable a el modo de red = NAT. Booleano para informar a WSL que configure el Servidor DNS en Linux en la instancia de NAT en el host. Si se establece en falso se reflejarán los servidores DNS de Windows a Linux.
networkingMode**	cadena	NAT	Si el valor es mirrored, se activa el modo de red reflejado. Las cadenas predeterminadas o no reconocidas producen redes NAT.
firewall**	booleano	true	Establecer esto en true permite que las reglas del Firewall de Windows, así como las reglas específicas del tráfico de Hyper-V, filtren el tráfico de red de WSL.
dnsTunneling**	booleano	true	Cambios en la forma en que las solicitudes DNS se envían de WSL a Windows
autoProxy*	booleano	true	Exige que WSL use la información del proxy HTTP de Windows
defaultVhdSize	size	1099511627776 (1TB)	Establezca el tamaño del disco duro virtual (VHD) que almacena el sistema de archivos de distribución de Linux (por ejemplo, Ubuntu). Se puede usar para limitar el tamaño máximo que puede ocupar un sistema de archivos de distribución.

Las entradas con el valor path deben ser rutas de acceso de Windows con barras invertidas escapadas, por ejemplo: C:\\Temp\\myCustomKernel

Las entradas con el valor size deben ser un tamaño seguido de una unidad, por ejemplo, 8GB o 512MB.

Las entradas con un * después del tipo de valor solo están disponibles en Windows 11.

Las entradas con un ** después del tipo de valor requieren Windows 11 versión 22H2 o superior.

Configuración experimental

Estas opciones son versiones preliminares opcionales de las características experimentales que pretendemos establecer como valor predeterminado en el futuro.

Etiqueta de sección de .wslconfig: [experimental]

Nombre del valor de configuración	Value	Valor predeterminado	Notas
autoMemoryReclaim	cadena	dropCache	Libera automáticamente la memoria almacenada en caché después de detectar el uso de CPU inactivo. Establézcalo en gradual para la liberación lenta y en dropCache para la liberación instantánea de memoria almacenada en caché.
sparseVhd	bool	false	Cuando se establece en true, cualquier VHD recién creado se definirá como disperso automáticamente.
bestEffortDnsParsing**	bool	false	Solo se aplica cuando wsl2.dnsTunneling se establece en true. Cuando se establece en true, Windows extraerá la pregunta de la solicitud DNS e intentará resolverla, ignorando los registros desconocidos.
dnsTunnelingIpAddress**	cadena	10.255.255.254	Solo se aplica cuando wsl2.dnsTunneling se establece en true. Especifica el servidor de nombres que se configurará en el archivo resolv.conf de Linux cuando esté habilitada la tunelización de DNS.
initialAutoProxyTimeout*	string	1000	Solo se aplica cuando wsl2.autoProxy se establece en true. Configura el tiempo (en milisegundos) que esperará WSL para recuperar la información del proxy HTTP al iniciar un contenedor WSL. Si la configuración del proxy se resuelve después de este tiempo, se debe reiniciar la instancia de WSL para usar la configuración de proxy recuperada.
ignoredPorts**	cadena	null	Solo se aplica cuando wsl2.networkingMode se establece en mirrored. Especifica los puertos a los que se pueden enlazar las aplicaciones Linux, incluso si ese puerto se usa en Windows. Esto permite que las aplicaciones monitoreen un puerto para el tráfico exclusivamente dentro de Linux, de modo que no se bloqueen incluso cuando ese puerto se use para otros fines en Windows. Por ejemplo, WSL permitirá enlazar al puerto 53 de Linux para Docker Desktop, ya que solo escucha solicitudes del contenedor de Linux. El formato debe ser una lista separada por comas, por ejemplo: 3000,9000,9090
hostAddressLoopback**	bool	false	Solo se aplica cuando wsl2.networkingMode se establece en mirrored. Cuando se establece en True, permitirá que el contenedor se conecte al host, o que el host se conecte al contenedor, mediante una dirección IP asignada al host. Siempre se puede usar la dirección de bucle invertido 127.0.0.1; esta opción también permite usar todas las direcciones IP locales asignadas. Solo se admiten las direcciones IPv4 asignadas al host.

Las entradas con un * después del tipo de valor solo están disponibles en Windows 11.

Las entradas con ** después del tipo de valor requieren Windows versión 22H2 o una posterior.

Archivo .wslconfig de ejemplo

El archivo de muestra a continuación demuestra algunas de las opciones de configuración disponibles. En este ejemplo, la ruta del archivo es 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

# 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

# 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 adicionales

• Blog de la línea de comandos de Windows: Configuración automática de WSL
• Blog de la línea de comandos de Windows: Chmod/Chown, DrvFs, metadatos de archivo