Compartir a través de

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:

  1. Un sistema de archivos raíz (distribuido como un archivo tar)
  2. Una entrada de manifiesto (que contiene los metadatos de distribución)

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:

  1. /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.
  2. /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]
enabled = true
icon = /usr/lib/wsl/my-icon.ico

[windowsterminal]
enabled = true
ProfileTemplate = /usr/lib/wsl/terminal-profile.json

Opciones de configuración del archivo de distribución de WSL:

clave valor Predeterminado. notas
oobe.command cuerda / cadena <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 entero <none> UID predeterminado con el que comienza la distribución. Esto resulta útil cuando el oobe.command script crea un nuevo usuario.
oobe.defaultName cuerda / cadena <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 cuerda / cadena 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
shortcut.enabled booleano cierto Si se debe crear un acceso directo del menú inicio cuando se instala la distribución.
windowsterminal.profileTemplate cuerda / cadena <none> Plantilla JSON para generar un perfil de Terminal Windows para esta distribución.
windowsterminal.enabled booleano cierto Si se debe crear un perfil de terminal cuando se instala la distribución. Si profileTemplate no se establece, se generará un perfil predeterminado.
windowsterminal.profileTemplate cuerda / cadena 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/sbin/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 las recomendaciones de Systemd si decide 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 el archivo tar.

La forma recomendada de crear el archivo 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 las recomendaciones del archivo de configuración para obtener una lista de archivos que deben incluirse y no deben incluirse en la configuración.

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 que se va a usar con WSL.

Una vez que el archivo de archivos tar esté listo, consulte Probar la distribución localmente para probarlo localmente.

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

El paso final, 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 .tar extensión de archivo cambiando su .wsl 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 del archivo tar de .tar a .wsl, el archivo se instalará correctamente en Windows cuando se abra (haga doble clic) en el 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 <distroName> 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.

El tar de distribución de Linux personalizado que usted ha creado y renombrado con la extensión de archivo .wsl se puede distribuir de la manera que desee. Una vez descargado un usuario puede instalarlo directamente desde la línea de comandos por wsl --install --from-file <fileLocation> (reemplazando <fileLocation> 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 de Linux 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

Añadiendo tu distribución en 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.

Añadir su distribución a wsl --install para su entorno empresarial o grupo de negocios

También puede hacer que la distribución solo esté disponible en wsl --install para un grupo seleccionado editando las claves del Registro en los dispositivos Windows elegidos.

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 la versión 2.4.4 de WSL, el file:// protocolo se admite para facilitar las pruebas locales. El formato esperado es: file:///C:/path/to/file.

Probar la distribución localmente

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 comando siguiente 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.

Recomendaciones de distribución de Linux personalizadas de WSL

Recomendaciones de archivos de configuración

  • Asegúrese de que la distribución personalizada incluye los archivos de /etc/wsl.conf configuración y /etc/wsl-distribution.conf . Ambos archivos deben ser propiedad de root:root y sus permisos deben ser 0644.
  • Si se usa la configuración oobe.command para crear un nuevo usuario, tanto uid como oobe.defaultUid deben establecerse a 1000.
  • Asegúrese de establecer ambos oobe.defaultName y shortcut.icon en el archivo de configuración de distribución: /etc/wsl-distribution.conf
  • No incluya el archivo /etc/resolv.conf en el sistema de archivos raíz.
  • Incluya un usuario raíz en /etc/passwd. El uid para este usuario raíz debe ser 0.
  • No debe haber ningún hash de contraseña en /etc/shadow.
  • El archivo no debe contener un kernel ni initramfs.

Recomendaciones de Systemd

Si systemd está habilitado, las unidades que pueden causar problemas con WSL deben deshabilitarse o enmascararse. Las siguientes unidades se sabe que causan problemas en las distribuciones de WSL (se aplica a las unidades del sistema y del 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