Configuración avanzada en WSL

Los archivos wsl.conf y .wslconfig se usan para configurar opciones de configuración avanzadas, por distribución (wsl.conf) y globalmente en todas las distribuciones de WSL 2 (.wslconfig). Esta guía abarcará cada una de las opciones de configuración, cuándo usar cada tipo de archivo, dónde almacenar el archivo, los archivos de configuración de ejemplo y las sugerencias.

¿Cuál es la diferencia entre wsl.conf y .wslconfig?

Puede configurar las opciones de las distribuciones de Linux instaladas que se aplicarán automáticamente cada vez que inicie WSL de dos maneras mediante:

  • .wslconfig para configurar las opciones globales en todas las distribuciones instaladas que se ejecutan en WSL 2.
  • wsl.conf para configurar las opciones locales por distribución para cada distribución de Linux que se ejecuta en WSL 1 o WSL 2.

Ambos tipos de archivo se usan para configurar las opciones de WSL, pero la ubicación donde se almacena el archivo, el ámbito de la configuración, el tipo de opciones que se pueden configurar y la versión de WSL que ejecuta la distribución afectan a qué tipo de archivo elegir.

WSL 1 y WSL 2 se ejecutan con una arquitectura diferente y afectarán a las opciones de configuración. WSL 2 se ejecuta como una máquina virtual ligera, por lo que usa la configuración de virtualización que le permite controlar la cantidad de memoria o procesadores usados (lo que puede resultar familiar si usa Hyper-V o VirtualBox). Comprobación de 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 iniciarse para dar tiempo suficiente para que se recojan los cambios. Puede comprobar si la distribución de Linux (shell) sigue ejecutándose después de cerrarla mediante 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 vía rápida para 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 al instante 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 de /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 ejecutadas por una versión, 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 debe 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. Compruebe la versión de WSL con el comando wsl --version. Si necesita actualizar, puede obtener la versión más reciente de WSL en Microsoft Store. Obtenga más información en el anuncio del blog.

Para habilitar systemd, abra el archivo wsl.conf en un editor de texto mediante sudo para permisos de administrador y agregue estas líneas a /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 los servicios.

Configuración de montaje automático

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

key value default notas
enabled boolean 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 boolean true true establece /etc/fstab para que se procese en el inicio de 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 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 deshabilitado
mayúsculas y minúsculas 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]

key value default notas
generateHosts boolean true true establece WSL para generar /etc/hosts. El archivo hosts contiene una asignación estática de direcciones IP correspondientes a nombres de host.
generateResolvConf boolean true true establece 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 sección de wsl.conf: [interop]

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

key value default notas
enabled boolean true La configuración de esta clave determinará si WSL admitirá el inicio de procesos de Windows.
appendWindowsPath boolean true Establecer esta clave determinará si WSL agregará elementos de ruta de acceso 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.

key value 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]

key value default notas
comando 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 ejemplo de wsl.conf que aparece a continuación muestra 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

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

  • El archivo .wslconfig no existe de manera predeterminada. Debe crearlo y almacenarlo en su directorio %UserProfile% para aplicar estas opciones 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 se puede usar 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 acceder al directorio, en PowerShell, use %UserProfile% para acceder al directorio de cd ~ principal (que suele ser el perfil de usuario, C:\Users\<UserName>) o puede 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]

key value default notas
kernel path Bandeja de entrada proporcionada por el kernel compilado de Microsoft Ruta de acceso absoluta de Windows a un kernel de Linux personalizado.
memory tamaño 50 % de memoria total en Windows u 8 GB, lo que sea menor; en compilaciones anteriores a la 20175: 80 % de la memoria total en Windows Cantidad de memoria que se va a asignar a la máquina virtual WSL 2.
procesadores 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 boolean 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 Blank Argumentos adicionales de la línea de comandos del kernel.
safeMode boolean 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 tamaño 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 máquina virtual de WSL 2, 0 para ningún 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 path %USERPROFILE%\AppData\Local\Temp\swap.vhdx Ruta de acceso absoluta de Windows al disco duro virtual de intercambio.
pageReporting boolean true La configuración predeterminada true permite a Windows reclamar 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. Solo está disponible para Windows 11.
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 número* 60000 Número de milisegundos que una máquina virtual está inactiva, antes de apagarla. Solo está disponible para Windows 11.
dnsProxy bool true Solo aplicable a networkingMode = NAT. Booleano para informar a WSL que configure el Servidor DNS en Linux al NAT en el host. Si se establece en falso se reflejarán los servidores DNS de Windows a Linux.
networkingMode** string NAT Si el valor es mirrored, se activa el modo de red reflejado. Las cadenas predeterminadas o no reconocidas producen redes NAT.
firewall** bool 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** bool false Cambios en la forma en que las solicitudes DNS se envían de WSL a Windows
autoProxy* bool false Exige que WSL use la información del proxy HTTP de Windows

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 Valor Valor predeterminado Notas
autoMemoryReclaim cadena deshabilitado Libera automáticamente la memoria almacenada en caché después de detectar el uso de CPU inactivo. Establézcalo en gradual para la versió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.
useWindowsDnsCache** bool false Solo se aplica cuando wsl2.dnsTunneling se establece en true. Cuando esta opción se establece en false, las solicitudes DNS de túnel desde Linux omitirán los nombres almacenados en caché en Windows para colocar siempre las solicitudes en la conexión.
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.
initialAutoProxyTimeout* cadena 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 escuchen en un puerto de tráfico puramente dentro de Linux, por lo que esas aplicaciones no se bloquean aunque 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 la versión 22H2 de Windows o una posterior.

Archivo .wslconfig de ejemplo

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

# 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