Créer une distribution Linux personnalisée pour WSL

Article
11/19/2024

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 :

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

Remarque

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

Remarque

Consultez ce référentiel pour obtenir les instructions d’empaquetage de distribution basées sur appx précédentes.

Qu’est-ce que les fichiers tar WSL système de fichiers racine ?

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 effectuer dans une 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 :

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

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

Options de configuration des fichiers de distribution WSL :

key	value	default	Remarques
`oobe.command`	string	`<none>`	OOBE se distingue par l’expérience prête à l’emploi. Cette commande exécute la première fois que l’utilisateur ouvre un interpréteur de commandes interactif dans la distribution. Si cette commande retourne non zéro, elle est considérée comme ayant échoué et l’utilisateur ne pourra pas ouvrir un interpréteur de commandes.
`oobe.defaultUid`	entier	`<none>`	UID par défaut que la distribution commence par. Cela est utile lorsque le `oobe.command` script crée un utilisateur.
`oobe.defaultName`	string	`<none>`	Nom par défaut sous lequel la distribution est inscrite. Ce nom par défaut peut être remplacé par la commande : `wsl.exe --install <distro> --name <name>`
`shortcut.icon`	string	Icône WSL par défaut	Icône dans le raccourci du menu Démarrer pour la distribution. Doit être au `.ico` format avec une taille maximale de `10MB`
'windowsterminal.profileTemplate'	string	Chemin d’accès à un fichier de modèle de terminal	Modèle JSON pour générer un profil Terminal Windows pour cette distribution.

Vous devez créer une expérience OOBE (Out Of Box Experience) pour la distribution. Vous trouverez ci-dessous un exemple de script bash que vous pouvez utiliser. Ce script suppose qu’il 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/bin/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 gestionnaires de maintenance de distribution peuvent personnaliser le profil généré 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’une système de fichiers racine de distribution, nous vous recommandons de configurer les paramètres système, notamment si le système démarre par défaut, dans les /etc/wsl.conf paramètres locaux par 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).

Consultez la section bonnes pratiques si vous avez choisi d’activer systemd par défaut.

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, la système de fichiers racine peut être capturée en tar.

Voici la façon recommandée de créer le 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 la section bonnes pratiques pour les fichiers qui doivent ou ne doivent pas être inclus

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 fichier tar prête, consultez Remplacer le manifeste de distribution 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 .tar fichier par une .wsl extension de fichier 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é à partir de .tar , .wslle fichier s’installe correctement sur Windows lors de l’ouverture (double-cliquez) dans Explorateur de fichiers. Une oobe.defaultName entrée est requise dans le /etc/wsl-distribution.conf fichier pour que cette expérience double-clic fonctionne correctement

Distribuer votre distribution WSL

Les utilisateurs WSL peuvent afficher les distributions disponibles en les exécutant wsl --list --online et les installer directement wsl --install <distroName> par (en remplaçant 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 tar de distribution Linux personnalisé que vous avez créé et renommé avec une .wsl extension de fichier peut être distribué, mais vous le souhaitez. Une fois téléchargé, un utilisateur peut l’installer directement à partir de la ligne wsl --install --from-file <fileLocation> de commande par (en remplaçant 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 basées sur 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 sha265 hash>"
        },
    "Arm64Url": {
        "Url": "<tar url>",
        "Sha256": "<tar sha265 hash>"
        }
    }
}

Chaque flavor entrée contient une liste de distributions installables. Les distributions peuvent être installées via le nom de la saveur (auquel cas l’entrée par défaut est installée) ou 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` tous les utilisateurs WSL

Pour rendre votre distribution WSL disponible pour tous les utilisateurs, ouvrez une demande de tirage sur le dépôt GitHub WSL qui modifie le fichier DistributionInfo.json pour inclure vos informations de distribution.

Cette demande de tirage sera examinée par l’équipe WSL.

Ajout de votre distribution pour `wsl --install` votre entreprise ou votre groupe

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

Le manifeste de distribution WSL peut être substitué 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 WSL 2.4.4, le file:// protocole est pris en charge pour faciliter les tests locaux. Le format attendu est le suivant : file:///C:/path/to/file

Test d’une distribution locale

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 comme override-manifest.ps1suit :

#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 powershell avec élévation de privilèges :

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

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

Bonnes pratiques

Fichiers de configuration

/etc/wsl.conf et /etc/wsl-distribution.conf devrait être inclus. Ils doivent être détenus par root:root et leurs autorisations doivent être 0644
Si oobe.command elle est utilisée pour créer un utilisateur, son uid doit être 1000défini sur oobe.defaultUid cette valeur.
oobe.defaultName et shortcut.icon doit être spécifié dans /etc/wsl-distribution.conf
/etc/resolv.confne doit PAS être inclus dans le système de fichiers racine
Il doit y avoir un utilisateur racine et /etc/passwd son uid doit ê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

Systemd

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 connues pour provoquer des problèmes dans les distributions WSL (s’appliquent 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

Partager via

Créer une distribution Linux personnalisée pour WSL

Qu’est-ce que les fichiers tar WSL système de fichiers racine ?

Créer des fichiers de configuration WSL

Ajouter le fichier de configuration de distribution WSL

Générer un profil Terminal Windows

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

Créer le fichier tar

Créer une extension de fichier .wsl

Distribuer votre distribution WSL

Détails du manifeste de distribution

Ajout de votre distribution à `wsl --install` tous les utilisateurs WSL

Ajout de votre distribution pour `wsl --install` votre entreprise ou votre groupe

Test d’une distribution locale

Bonnes pratiques

Fichiers de configuration

Systemd

Ressources supplémentaires

Partager via

Créer une distribution Linux personnalisée pour WSL

Qu’est-ce que les fichiers tar WSL système de fichiers racine ?

Créer des fichiers de configuration WSL

Ajouter le fichier de configuration de distribution WSL

Générer un profil Terminal Windows

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

Créer le fichier tar

Créer une extension de fichier .wsl

Distribuer votre distribution WSL

Détails du manifeste de distribution

Ajout de votre distribution à wsl --install tous les utilisateurs WSL

Ajout de votre distribution pour wsl --install votre entreprise ou votre groupe

Test d’une distribution locale

Bonnes pratiques

Fichiers de configuration

Systemd

Ressources supplémentaires

Ajout de votre distribution à `wsl --install` tous les utilisateurs WSL

Ajout de votre distribution pour `wsl --install` votre entreprise ou votre groupe