Compilación de una distribución personalizada de Linux para WSL
En esta guía se describen los pasos para crear y distribuir una distribución de WSL, que es un .wsl
archivo.
Las distribuciones de WSL tienen dos partes:
- Un sistema de archivos raíz (distribuido como un archivo tar)
- Una entrada de manifiesto (que contiene los metadatos de distribución)
Nota
Esta guía solo se aplica a la versión 2.4.4 y posteriores de WSL.
Nota
Consulte este repositorio para obtener las instrucciones de empaquetado de distribución basadas en appx anteriores.
Las distribuciones de WSL se definen mediante un archivo tar con una .wsl
extensión de archivo en Windows.
Un archivo TAR (short for Tape Archive) es un tipo de archivo que se usa para almacenar varios archivos juntos en un único archivo para facilitar la distribución o copia de seguridad. El archivo TAR contiene el sistema de archivos raíz de una distribución de Linux (todos los archivos de distribución), así como los archivos de configuración de WSL. Los archivos de configuración de WSL indican al sistema operativo WIndows cómo instalar e iniciar la distribución.
Una vez que tenga un sistema Linux que le gustaría realizar en una distribución de WSL, siga los pasos que se indican a continuación para empezar.
Hay dos archivos de configuración que la distribución debe incluir:
/etc/wsl-distribution.conf
: un archivo creado por el mantenedor de distribución responsable de controlar cómo se debe configurar la distribución de Linux cuando se inicia por primera vez con WSL./etc/wsl.conf
: un archivo que contiene la configuración global del sistema que es específica del usuario y controla cómo se inicia la distribución. Obtenga más información sobre los archivos de configuración de WSL.
El archivo de configuración de distribución, /etc/wsl-distribution.conf
, define cómo se debe configurar la distribución de Linux cuando el usuario lo inicie por primera vez. Este archivo se puede usar para crear interactivamente una cuenta de usuario, mostrar un contrato de licencia, etc.
Este es un archivo de ejemplo /etc/wsl-distribution.conf
:
# /etc/wsl-distribution.conf
[oobe]
command = /etc/oobe.sh
defaultUid = 1000
defaultName = my-distro
[shortcut]
icon = /usr/lib/wsl/my-icon.ico
[windowsterminal]
ProfileTemplate = /usr/lib/wsl/terminal-profile.json
Opciones de configuración del archivo de distribución de WSL:
key | value | default | notas |
---|---|---|---|
oobe.command |
string | <none> |
OOBE destaca por la experiencia lista para usar. Este comando ejecuta la primera vez que el usuario abre un shell interactivo en la distribución. Si ese comando devuelve un valor distinto de cero, se considera incorrecto y el usuario no podrá abrir un shell. |
oobe.defaultUid |
integer | <none> |
UID predeterminado con el que comienza la distribución. Esto resulta útil cuando el oobe.command script crea un nuevo usuario. |
oobe.defaultName |
string | <none> |
Nombre predeterminado en el que se registra la distribución. Este nombre predeterminado se puede reemplazar por el comando : wsl.exe --install <distro> --name <name> |
shortcut.icon |
string | Icono de WSL predeterminado | Icono del acceso directo del menú inicio para la distribución. Debe estar en .ico formato con un tamaño máximo de 10MB |
'windowsterminal.profileTemplate' | string | Ruta de acceso a un archivo de plantilla de terminal | Plantilla JSON para generar un perfil de Terminal Windows para esta distribución. |
Debe crear una experiencia rápida (OOBE) para la distribución. A continuación se muestra un script de bash de ejemplo que puede usar. Este script supone que oobe.defaultUid
está establecido 1000
en :
#! /bin/bash
set -ue
DEFAULT_GROUPS='adm,cdrom,sudo,dip,plugdev'
DEFAULT_UID='1000'
echo 'Please create a default UNIX user account. The username does not need to match your Windows username.'
echo 'For more information visit: https://aka.ms/wslusers'
if getent passwd "$DEFAULT_UID" > /dev/null ; then
echo 'User account already exists, skipping creation'
exit 0
fi
while true; do
# Prompt from the username
read -p 'Enter new UNIX username: ' username
# Create the user
if /usr/sbin/adduser --uid "$DEFAULT_UID" --quiet --gecos '' "$username"; then
if /usr/sbin/usermod "$username" -aG "$DEFAULT_GROUPS"; then
break
else
/usr/bin/deluser "$username"
fi
fi
done
WSL genera automáticamente un perfil de Terminal Windows cuando se instala una distribución. Los mantenedores de distribución pueden personalizar el perfil generado estableciendo windowsterminal.profileTemplate
en el archivo de configuración de WSL, /etc/wsl-distribution.conf
.
El archivo json sigue el formato json del perfil de terminal. Este es un perfil de ejemplo:
{
"profiles": [
{
"antialiasingMode": "aliased",
"fontWeight": "bold",
"colorScheme": "Postmodern Tango Light"
}
],
"schemes": [
{
"name": "Postmodern Tango Light",
"black": "#0C0C0C",
"red": "#C50F1F",
"green": "#13A10E",
"yellow": "#C19C00",
"blue": "#0037DA",
"purple": "#881798",
"cyan": "#3A96DD",
"white": "#CCCCCC",
"brightBlack": "#767676",
"brightRed": "#E74856",
"brightGreen": "#16C60C",
"brightYellow": "#F9F1A5",
"brightBlue": "#3B78FF",
"brightPurple": "#B4009E",
"brightCyan": "#61D6D6",
"brightWhite": "#F2F2F2"
}
]
}
Este archivo no necesita especificar el perfil name
ni commandLine
. WSL agrega automáticamente esos elementos al generar el perfil de terminal.
En el contexto de un sistema de archivos raíz de distribución, se recomienda configurar las opciones del sistema, incluido si el sistema se inicia de forma predeterminada, en la /etc/wsl.conf
configuración local por distribución. Observe el ejemplo siguiente.
# /etc/wsl.conf
[boot]
systemd=true|false
El autor de distribución determina si systemd está habilitado de forma predeterminada estableciendo el boot.systemd
valor true
en (habilitado) o false
(no habilitado).
Consulte la sección procedimientos recomendados si eligió habilitar systemd de forma predeterminada.
Consulte Configuración avanzada de configuración en WSL para ver todas las opciones admitidas en /etc/wsl.conf
.
Una vez que se han implementado los archivos de distribución y configuración, el sistema de archivos raíz se puede capturar en tar.
A continuación se muestra la manera recomendada de crear el tar:
$ cd /path/to/rootfs
$ tar --numeric-owner --absolute-names -c * | gzip --best > ../install.tar.gz
La raíz del archivo tar debe ser la raíz del sistema de archivos (no un directorio que contenga el sistema de archivos raíz).
El formato de compresión recomendado es gzip. Otros formatos de compresión corren el riesgo de interrumpir la compatibilidad con versiones anteriores de WSL.
Consulte la sección procedimientos recomendados para los archivos que deben incluirse o no deben incluirse.
Para obtener un archivo TAR de una distribución de Linux existente, busque instrucciones sobre cómo exportar un contenedor de Docker en Importación de cualquier distribución de Linux para su uso con WSL.
Una vez que el archivo de archivos tar esté listo, consulte Invalidación del manifiesto de distribución para probarlo localmente.
El último paso, una vez que haya creado un archivo TAR para representar la distribución personalizada de Linux, es cambiar la extensión de archivo a una .wsl
extensión de archivo cambiando el .tar
nombre. Al cambiar el nombre de esta extensión de archivo, se marcará como una distribución de WSL. Una vez que se ha cambiado el nombre de TAR de .tar
a .wsl
, el archivo se instalará correctamente en Windows cuando se abra (haga doble clic) en Explorador de archivos. Se requiere una oobe.defaultName
entrada en el /etc/wsl-distribution.conf
archivo para que esta experiencia de doble clic funcione correctamente.
Los usuarios de WSL pueden ver las distribuciones disponibles mediante la ejecución wsl --list --online
de y pueden instalarlas directamente con wsl --install <distroName>
(reemplazando por el nombre real de la distribución de Linux. Este proceso se controla mediante un archivo de manifiesto de distribución. Puede agregar este archivo de manifiesto a la distribución de Linux del cliente para que se incluya en las opciones de wsl --install
comando.
La TAR de distribución personalizada de Linux que ha creado y cambiado el nombre con una .wsl
extensión de archivo se puede distribuir sin embargo. Una vez descargado un usuario puede instalarlo directamente desde la línea de comandos por wsl --install --from-file <fileLocation>
(reemplazando por la ubicación real del archivo). Como alternativa, el .wsl
archivo de la distribución de WSL personalizada se puede abrir haciendo doble clic en él.
El manifiesto de distribución contiene metadatos sobre las distribuciones disponibles para la instalación a través wsl --install <distribution>
de .
Las distribuciones basadas en TAR se enumeran en ModernDistribution
, con el formato siguiente:
"ModernDistributions": {
"<flavor>": [
{
"Name": "<version name>",
"FriendlyName": "<friendly name>",
"Default": true | false,
"Amd64Url": {
"Url": "<tar url>",
"Sha256": "<tar sha265 hash>"
},
"Arm64Url": {
"Url": "<tar url>",
"Sha256": "<tar sha265 hash>"
}
}
}
Cada flavor
entrada contiene una lista de distribuciones instalables. Las distribuciones se pueden instalar a través del nombre de tipo (en cuyo caso está instalada la entrada predeterminada) o el nombre de la versión.
Vea cómo wsl --install
funcionan los comandos con el siguiente manifiesto:
{
"ModernDistributions": {
"my-distro": [
{
"Name": "my-distro-v3",
"Default": true,
"FriendlyName": "My distribution version 3 (latest)"
[...]
},
{
"Name": "my-distro-v2",
"Default": false,
"FriendlyName": "My distribution version 2"
[...]
}
}
}
Comandos de instalación de ejemplo:
$ wsl --install my-distro # Installs 'my-distro-v3' since it's the default for 'my-distro' flavor
$ wsl --install my-distro-v3 # Installs 'my-distro-v3' explicitly
$ wsl --install my-distro-v2 # Installs 'my-distro-v2' explicitly
Para que la distribución de WSL esté disponible para todos los usuarios, abra una solicitud de incorporación de cambios en el repositorio de GitHub de WSL que modifique el archivo DistributionInfo.json para incluir la información de distribución.
El equipo de WSL revisará esta solicitud de incorporación de cambios.
También puede hacer que la distribución solo esté disponible en wsl --install
un grupo seleccionado editando las claves del Registro en las máquinas elegidas.
El manifiesto de distribución de WSL se puede invalidar mediante la creación de valores del Registro en HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss
.
DistributionListUrl
: invalida la dirección URL del manifiesto de distribución.DistributionListUrlAppend
: se agregan distribuciones de esa dirección URL de manifiesto a la lista de distribuciones instalables.
Ambos valores del Registro son cadenas (REG_SZ) y se espera que estén en formato de dirección URL.
A partir de WSL 2.4.4, se admite el file://
protocolo para facilitar las pruebas locales. El formato esperado es: file:///C:/path/to/file
Para probar un tar de distribución, puede usar el siguiente script de PowerShell de ejemplo para invalidar el manifiesto de distribución con la nueva distribución. En primer lugar, guarde el script siguiente como override-manifest.ps1
:
#Requires -RunAsAdministrator
[cmdletbinding(PositionalBinding = $false)]
param (
[Parameter(Mandatory = $true)][string]$TarPath,
[string]$Flavor = "test-distro",
[string]$Version = "test-distro-v1",
[string]$FriendlyName = "Test distribution version 1")
Set-StrictMode -Version latest
$TarPath = Resolve-Path $TarPath
$hash = (Get-Filehash $TarPath -Algorithm SHA256).Hash
$manifest= @{
ModernDistributions=@{
"$Flavor" = @(
@{
"Name" = "$Version"
Default = $true
FriendlyName = "$FriendlyName"
Amd64Url = @{
Url = "file://$TarPath"
Sha256 = "0x$hash"
}
})
}
}
$manifestFile = "$PSScriptRoot/manifest.json"
$manifest | ConvertTo-Json -Depth 5 | Out-File -encoding ascii $manifestFile
Set-ItemProperty -Path "HKLM:SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss" -Name DistributionListUrl -Value "file://$manifestFile" -Type String -Force
A continuación, configure el manifiesto local mediante la ejecución del siguiente comando en un powershell con privilegios elevados:
.\override-manifest.ps1 -TarPath /path/to/tar
Una vez completado, debería ver la salida siguiente de . wsl.exe --list --online
$ wsl --list --online
The following is a list of valid distributions that can be installed.
Install using 'wsl.exe --install <Distro>'.
NAME FRIENDLY NAME
test-distro-v1 Test distribution version 1
A continuación, puede ejecutar wsl.exe --install test-distro-v1
para probar la instalación de la nueva distribución.
Cuando haya terminado, puede eliminar HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl
para revertir al manifiesto oficial.
/etc/wsl.conf
y/etc/wsl-distribution.conf
deben incluirse. Deben ser propiedadroot:root
de y sus permisos deben ser0644
- Si
oobe.command
se usa para crear un nuevo usuario, su uid debe ser1000
y debeoobe.defaultUid
establecerse en ese valor. oobe.defaultName
yshortcut.icon
deben especificarse en/etc/wsl-distribution.conf
/etc/resolv.conf
NO debe incluirse en el sistema de archivos raíz- Debe haber un usuario raíz en
/etc/passwd
y su uid debe ser0
- No debe haber ningún hash de contraseña en
/etc/shadow
- El archivo no debe contener un kernel ni un initramfs
Si systemd está habilitado, las unidades que pueden causar problemas con WSL deben deshabilitarse o enmascararse. Las unidades siguientes que se sabe que causan problemas en las distribuciones de WSL (se aplican a las unidades de sistema y de usuario):
- systemd-resolved.service
- systemd-networkd.service
- NetworkManager.service
- systemd-tmpfiles-setup.service
- systemd-tmpfiles-clean.service
- systemd-tmpfiles-clean.timer
- systemd-tmpfiles-setup-dev-early.service
- systemd-tmpfiles-setup-dev.service
- tmp.mount
Comentarios de Windows Subsystem for Linux
Windows Subsystem for Linux es un proyecto de código abierto. Seleccione un vínculo para proporcionar comentarios: