Créer une distribution Linux personnalisée pour WSL

Ce guide décrit les étapes de création et de distribution d’une distribution WSL, qui est un .wsl fichier.

Les distributions WSL ont deux parties :

1. Un système de fichiers racine (distribué en tant que fichier tar)
2. Entrée de manifeste (qui contient les métadonnées de distribution)

Ce guide s’applique uniquement à WSL release 2.4.4 et versions ultérieures.

Qu'est-ce qu'un fichier tar du système de fichiers racine WSL ?

Les distributions WSL sont définies par un fichier tar avec une .wsl extension de fichier sur Windows.

Un fichier TAR (short for Tape Archive) est un type de fichier d’archive utilisé pour stocker plusieurs fichiers ensemble dans un seul fichier pour faciliter la distribution ou la sauvegarde. Le fichier TAR contient le système de fichiers racine d’une distribution Linux (tous les fichiers de distribution), ainsi que les fichiers de configuration WSL. Les fichiers de configuration WSL indiquent au système d’exploitation WIndows comment installer et lancer la distribution.

Une fois que vous disposez d’un système Linux que vous souhaitez transformer en distribution WSL, suivez les étapes ci-dessous pour commencer.

Créer des fichiers de configuration WSL

Il existe deux fichiers de configuration que la distribution doit inclure :

1. /etc/wsl-distribution.conf: fichier créé par le responsable de la maintenance de distribution chargé de contrôler la configuration de la distribution Linux lors du premier lancement avec WSL.
2. /etc/wsl.conf: fichier contenant des paramètres système globaux spécifiques à l’utilisateur et contrôle la façon dont la distribution est lancée. En savoir plus sur les fichiers de configuration WSL..

Ajouter le fichier de configuration de distribution WSL

Le fichier de configuration de distribution, /etc/wsl-distribution.confdéfinit la façon dont la distribution Linux doit être configurée lors du premier lancement de l’utilisateur. Ce fichier peut être utilisé pour créer de manière interactive un compte d’utilisateur, afficher un contrat de licence, etc.

Voici un exemple /etc/wsl-distribution.conf de fichier :

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

Options de configuration des fichiers de distribution WSL :

Vous devez créer une expérience prête à l’emploi (OOBE) de première utilisation pour la distribution. Vous trouverez ci-dessous un exemple de script bash que vous pouvez utiliser. Ce script suppose que oobe.defaultUid est défini sur 1000:‍

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

Générer un profil Terminal Windows

WSL génère automatiquement un profil Terminal Windows lorsqu’une distribution est installée. Les mainteneurs de distribution peuvent personnaliser le profil généré en définissant windowsterminal.profileTemplate dans le fichier de configuration WSL. /etc/wsl-distribution.conf

Le fichier json suit le format json du profil terminal. Voici un exemple de profil :

{
  "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"
    }
  ]
}

Ce fichier n’a pas besoin de spécifier le profil name, ou commandLine. Ceux-ci sont automatiquement ajoutés par WSL lors de la génération du profil de terminal.

Ajouter une configuration WSL pour les paramètres locaux par distribution

Dans le contexte d'un système de fichiers racine de distribution, nous vous recommandons de configurer les paramètres systemd, y compris si systemd démarre par défaut, dans les /etc/wsl.conf paramètres locaux pour chaque distribution. Reportez-vous à l’exemple ci-dessous.

# /etc/wsl.conf

[boot]
systemd=true|false

L’auteur de distribution détermine si systemd est activé par défaut en définissant la boot.systemd valeur true sur (activée) ou false (non activée).

Si vous avez choisi d’activer Systemd par défaut, consultez les Recommandations systemd.

Consultez la configuration des paramètres avancés dans WSL pour tous les paramètres pris en charge dans /etc/wsl.conf.

Créer le fichier tar

Une fois les fichiers de distribution et de configuration en place, le système de fichiers racine peut être capturé dans le fichier tar.

La méthode recommandée pour créer le fichier tar :

cd /path/to/rootfs
tar --numeric-owner --absolute-names -c  * | gzip --best > ../install.tar.gz

La racine du tar doit être la racine du système de fichiers (et non un répertoire contenant le système de fichiers racine).

Le format de compression recommandé est gzip. Les autres formats de compression courent le risque de rupture de compatibilité avec les anciennes versions de WSL.

Consultez les recommandations des fichiers de configuration pour obtenir la liste des fichiers qui doivent et ne doivent pas être inclus dans la configuration.

Pour obtenir un fichier tar d’une distribution Linux existante, découvrez comment exporter un conteneur Docker dans Importer une distribution Linux à utiliser avec WSL.

Une fois l’archive de fichiers tar prête, consultez Tester la distribution localement pour l’essayer localement.

Créer une extension de fichier .wsl

La dernière étape, une fois que vous avez créé un fichier tar pour représenter votre distribution Linux personnalisée, consiste à remplacer l’extension de fichier .tar par une extension de fichier .wsl en la renommant. Le changement de nom de cette extension de fichier le marque comme une distribution WSL. Une fois que le tar a été renommé de .tar en .wsl, le fichier s’installe correctement sur Windows lors de l’ouverture (double-clic) dans l’Explorateur de fichiers. Une entrée oobe.defaultName est requise dans le fichier /etc/wsl-distribution.conf pour que cette expérience double-clic fonctionne correctement.

Distribuer votre distribution WSL

Les utilisateurs WSL peuvent afficher les distributions disponibles en exécutant wsl --list --online et les installer directement avec wsl --install <distroName> (en remplaçant <distroName> par le nom réel de la distribution Linux. Ce processus est contrôlé par un fichier manifeste de distribution. Vous pouvez ajouter ce fichier manifeste à votre distribution Linux client pour qu’il soit inclus dans les options de wsl --install commande.

Le fichier "tar" de votre distribution Linux personnalisée, que vous avez créé et renommé avec une extension de fichier ..wsl, peut être distribué comme bon vous semble. Une fois téléchargé, un utilisateur peut l’installer directement à partir de la ligne de commande par wsl --install --from-file <fileLocation> (en remplaçant <fileLocation> par l’emplacement réel du fichier). Vous pouvez également ouvrir le .wsl fichier de votre distribution WSL personnalisée en double-cliquant dessus.

Détails du manifeste de distribution

Le manifeste de distribution contient des métadonnées sur les distributions disponibles pour l’installation via wsl --install <distribution>.

Les distributions Linux qui sont basées sur le tar sont répertoriées sous ModernDistribution, avec le format ci-dessous :

{
    "ModernDistributions": {
        "<flavor>": [
            {
                "Name": "<version name>",
                "FriendlyName": "<friendly name>",
                "Default": true | false,
                "Amd64Url": {
                    "Url": "<tar url>",
                    "Sha256": "<tar sha256 hash>"
                },
                "Arm64Url": {
                    "Url": "<tar url>",
                    "Sha256": "<tar sha256 hash>"
                }
            },
            {
                ...
            }
        ],
        "<flavor>": [
            ...
        ]
    }
}

Chaque flavor entrée contient une liste de distributions installables. Les distributions peuvent être installées soit par le nom de la version (auquel cas l’entrée par défaut est installée), soit par le nom de la version.

Découvrez comment wsl --install les commandes fonctionnent avec le manifeste ci-dessous :

{
    "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"
                [...]
            }
        ]
    }
}

Exemples de commandes d’installation :

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

Ajout de votre distribution à wsl --install pour l'ensemble des utilisateurs de WSL

Pour que votre distribution soit incluse dans la liste de la commande : wsl --list --onlinela distribution doit respecter les critères d’appartenance décrits dans la liste de diffusion de distribution. Cela garantit que toutes les distributions répertoriées respectent les normes de sécurité nécessaires.

Si votre distribution répond aux critères et que vous souhaitez l’ajouter à la --install liste, envoyez une demande de tirage sur le dépôt GitHub WSL (https://github.com/microsoft/WSL) qui met à jour le fichierDistributionInfo.json avec les détails de votre distribution. Cette proposition de fusion sera examinée par l’équipe WSL.

Ajout de votre solution de distribution à wsl --install pour votre entreprise ou votre groupe d’entreprises

Vous pouvez également rendre votre distribution disponible dans wsl --install uniquement à un groupe sélectionné en modifiant les clés de Registre sur les appareils Windows choisis.

Le manifeste de distribution WSL peut être remplacé en créant des valeurs de registre dans HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss.

• DistributionListUrl: remplace l’URL du manifeste de distribution
• DistributionListUrlAppend: Ajouter des distributions de cette URL de manifeste à la liste des distributions installables

Les deux valeurs de Registre sont des chaînes (REG_SZ) et sont censées être au format URL.

À compter de la version WSL 2.4.4, le protocole file:// est pris en charge pour faciliter les tests locaux. Le format attendu est : file:///C:/path/to/file.

Tester la distribution localement

Pour tester un tar de distribution, vous pouvez utiliser l’exemple de script PowerShell suivant pour remplacer le manifeste de distribution par la nouvelle distribution. Tout d'abord, enregistrez le script ci-dessous sous 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

Configurez ensuite le manifeste local en exécutant la commande suivante dans une instance PowerShell avec élévation de privilèges :

.\override-manifest.ps1 -TarPath /path/to/tar

Une fois terminé, vous devez voir la sortie suivante 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

Vous pouvez ensuite exécuter wsl.exe --install test-distro-v1 pour essayer l’installation de la nouvelle distribution.

Lorsque vous avez terminé, vous pouvez supprimer HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl pour revenir au manifeste officiel.

Recommandations de distribution Linux personnalisées WSL

Recommandations relatives aux fichiers de configuration

• Vérifiez que votre distribution personnalisée inclut les fichiers de configuration /etc/wsl.conf et /etc/wsl-distribution.conf. Les deux fichiers doivent être détenus par root:root et leurs autorisations doivent être 0644.
• Si le paramètre oobe.command est utilisé pour créer un utilisateur, uid et oobe.defaultUid doivent être définis sur 1000.
• Vérifiez que vous définissez les oobe.defaultName et les shortcut.icon dans le fichier de configuration de distribution : /etc/wsl-distribution.conf
• N’incluez pas le fichier /etc/resolv.conf dans le système de fichiers racine.
• Incluez un utilisateur racine dans /etc/passwd. Le uid de cet utilisateur racine devrait être 0.
• Il ne doit y avoir aucun hachage de mot de passe dans /etc/shadow.
• L’archive ne doit pas contenir de noyau ou d’initramfs.

Recommandations système

Si le système est activé, les unités qui peuvent provoquer des problèmes avec WSL doivent être désactivées ou masquées. Les unités ci-dessous sont connues pour provoquer des problèmes dans les distributions WSL (s’applique aux unités système et utilisateur) :

• 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