Compilación de una distribución personalizada de Linux para WSL

Artículo
11/19/2024

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.

¿Qué son los archivos tar del sistema de archivos raíz de WSL?

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.

Creación de archivos de configuración de WSL

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.

Adición del archivo de configuración de distribució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 1000en :

#! /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

Generación de un perfil de Terminal Windows

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 nameni commandLine. WSL agrega automáticamente esos elementos al generar el perfil de terminal.

Adición de una configuración de WSL para la configuración local por distribución

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.

Creación del archivo tar

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.

Creación de una extensión de archivo .wsl

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.

Distribuir la distribución de WSL

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.

Detalles del manifiesto de distribución

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

Adición de la distribución a `wsl --install` para todos los usuarios de WSL

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.

Adición de la distribución a `wsl --install` para su empresa o grupo

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

Prueba de una distribución local

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.

procedimientos recomendados

Archivos de configuración

/etc/wsl.conf y /etc/wsl-distribution.conf deben incluirse. Deben ser propiedad root:root de y sus permisos deben ser 0644
Si oobe.command se usa para crear un nuevo usuario, su uid debe ser 1000y debe oobe.defaultUid establecerse en ese valor.
oobe.defaultName y shortcut.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 ser 0
No debe haber ningún hash de contraseña en /etc/shadow
El archivo no debe contener un kernel ni un initramfs

Systemd

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

Compartir a través de

Compilación de una distribución personalizada de Linux para WSL

¿Qué son los archivos tar del sistema de archivos raíz de WSL?

Creación de archivos de configuración de WSL

Adición del archivo de configuración de distribución de WSL

Generación de un perfil de Terminal Windows

Adición de una configuración de WSL para la configuración local por distribución

Creación del archivo tar

Creación de una extensión de archivo .wsl

Distribuir la distribución de WSL

Detalles del manifiesto de distribución

Adición de la distribución a `wsl --install` para todos los usuarios de WSL

Adición de la distribución a `wsl --install` para su empresa o grupo

Prueba de una distribución local

procedimientos recomendados

Archivos de configuración

Systemd

Recursos adicionales

Compartir a través de

Compilación de una distribución personalizada de Linux para WSL

¿Qué son los archivos tar del sistema de archivos raíz de WSL?

Creación de archivos de configuración de WSL

Adición del archivo de configuración de distribución de WSL

Generación de un perfil de Terminal Windows

Adición de una configuración de WSL para la configuración local por distribución

Creación del archivo tar

Creación de una extensión de archivo .wsl

Distribuir la distribución de WSL

Detalles del manifiesto de distribución

Adición de la distribución a wsl --install para todos los usuarios de WSL

Adición de la distribución a wsl --install para su empresa o grupo

Prueba de una distribución local

procedimientos recomendados

Archivos de configuración

Systemd

Recursos adicionales

Adición de la distribución a `wsl --install` para todos los usuarios de WSL

Adición de la distribución a `wsl --install` para su empresa o grupo