Erstellen einer benutzerdefinierten Linux-Verteilung für WSL

Artikel
11/19/2024

In diesem Handbuch werden die Schritte zum Erstellen und Verteilen einer WSL-Verteilung erläutert, bei der es sich um eine .wsl Datei handelt.

WSL-Verteilungen weisen zwei Teile auf:

Eine Stammdateisystem (verteilt als Tar-Datei)
Ein Manifesteintrag (der die Verteilungsmetadaten enthält)

Hinweis

Diese Anleitung gilt nur für WSL-Version 2.4.4 und höher.

Hinweis

Lesen Sie dieses Repository für die vorherigen Appx-basierten Verteilungspaketanweisungen.

Was sind WSL-Stammdateisystem Tar-Dateien?

WSL-Verteilungen werden durch eine Tar-Datei mit einer .wsl Dateierweiterung unter Windows definiert.

Eine TAR-Datei (kurz für Bandarchiv) ist eine Art von Archivdatei, die verwendet wird, um mehrere Dateien zusammen in einer einzigen Datei zu speichern, um die Verteilung oder Sicherung zu vereinfachen. Die TAR-Datei enthält das Stammdateisystem einer Linux-Verteilung (alle Verteilungsdateien) sowie die WSL-Konfigurationsdateien. WSL-Konfigurationsdateien teilen dem WIndows-Betriebssystem mit, wie die Verteilung installiert und gestartet wird.

Sobald Sie über ein Linux-System verfügen, das Sie in eine WSL-Verteilung umwandeln möchten, führen Sie die folgenden Schritte aus, um zu beginnen.

Erstellen von WSL-Konfigurationsdateien

Es gibt zwei Konfigurationsdateien, die die Verteilung enthalten sollte:

/etc/wsl-distribution.conf: Eine Datei, die vom Verteilungsbetreuer erstellt wurde, die dafür verantwortlich ist, zu steuern, wie die Linux-Verteilung beim ersten Start mit WSL konfiguriert werden soll.
/etc/wsl.conf: Eine Datei mit globalen Systemeinstellungen, die für den Benutzer spezifisch sind, und steuern, wie die Verteilung gestartet wird. Weitere Informationen zu WSL-Konfigurationsdateien.

Hinzufügen der WSL-Verteilungskonfigurationsdatei

Die Verteilungskonfigurationsdatei definiert, /etc/wsl-distribution.confwie die Linux-Verteilung beim ersten Start durch den Benutzer konfiguriert werden soll. Diese Datei kann verwendet werden, um ein Benutzerkonto interaktiv zu erstellen, einen Lizenzvertrag anzuzeigen usw.

Hier ist eine Beispieldatei /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

Konfigurationsoptionen für WSL-Verteilungsdateien:

Schlüssel	value	default	Notizen
`oobe.command`	Zeichenfolge	`<none>`	Die Windows-Willkommensseite steht für out of box experience. Dieser Befehl wird ausgeführt, wenn der Benutzer zum ersten Mal eine interaktive Shell in der Verteilung öffnet. Wenn dieser Befehl ungleich Null zurückgibt, wird er als nicht erfolgreich betrachtet, und der Benutzer kann keine Shell öffnen.
`oobe.defaultUid`	integer	`<none>`	Die Standard-UID, mit der die Verteilung beginnt. Dies ist nützlich, wenn das `oobe.command` Skript einen neuen Benutzer erstellt.
`oobe.defaultName`	Zeichenfolge	`<none>`	Der Standardname, unter dem die Verteilung registriert ist. Dieser Standardname kann durch den Befehl ersetzt werden: `wsl.exe --install <distro> --name <name>`
`shortcut.icon`	Zeichenfolge	Das WSL-Standardsymbol	Das Symbol in der Startmenüverknüpfung für die Verteilung. Muss im `.ico` Format mit einer maximalen Größe von `10MB`
'windowsterminal.profileTemplate'	Zeichenfolge	Pfad zu einer Terminalvorlagendatei	Die JSON-Vorlage zum Generieren eines Windows-Terminal Profils für diese Verteilung.

Sie müssen eine Out-of-Box-Erfahrung (OOBE) für die erste Ausführung für die Verteilung erstellen. Nachfolgend finden Sie ein Beispiel für ein Bash-Skript, das Sie verwenden können. Für dieses Skript wird davon ausgegangen, dass oobe.defaultUid folgendes 1000festgelegt ist:

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

Generieren eines Windows-Terminal Profils

WSL generiert automatisch ein Windows-Terminal Profil, wenn eine Verteilung installiert wird. Verteilungsbetreuer können das generierte Profil anpassen, das durch Festlegen windowsterminal.profileTemplate in der WSL-Konfigurationsdatei generiert wird. /etc/wsl-distribution.conf

Die JSON-Datei folgt dem Json-Format des Terminalprofils. Hier ist ein Beispielprofil:


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

Diese Datei muss das Profil oder commandLinedas Profil namenicht angeben. Diese werden automatisch von WSL beim Generieren des Terminalprofils hinzugefügt.

Hinzufügen einer WSL-Konfiguration für lokale Einstellungen pro Verteilung

Im Kontext einer Verteilung Stammdateisystem wird empfohlen, systembasierte Einstellungen zu konfigurieren, einschließlich der Standardmäßigen Systemstarteinstellungen in den /etc/wsl.conf lokalen Einstellungen pro Verteilung. Betrachten Sie das folgende Beispiel.

# /etc/wsl.conf

[boot]
systemd=true|false

Der Verteilungsautor bestimmt, ob systemd standardmäßig aktiviert ist, indem der boot.systemd Wert auf true (aktiviert) oder false (nicht aktiviert) festgelegt wird.

Weitere Informationen finden Sie im Abschnitt "Bewährte Methoden" , wenn Sie das System standardmäßig aktivieren möchten.

Weitere Informationen finden Sie unter "Erweiterte Einstellungskonfiguration" in WSL für alle unterstützten Einstellungen in /etc/wsl.conf.

Erstellen der Tar-Datei

Sobald die Verteilungs- und Konfigurationsdateien vorhanden sind, kann die Stammdateisystem in Tar erfasst werden.

Im Folgenden finden Sie die empfohlene Methode zum Erstellen des Tars:

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

Der Stamm des Tar sollte das Stammverzeichnis des Dateisystems sein (kein Verzeichnis, das die Stammdateisystem enthält).

Das empfohlene Komprimierungsformat ist gzip. Bei anderen Komprimierungsformaten besteht das Risiko, die Kompatibilität mit älteren WSL-Versionen zu unterbrechen.

Weitere Informationen finden Sie im Abschnitt "Bewährte Methoden" für Dateien, die nicht enthalten sein sollten.

Um eine TAR-Datei einer vorhandenen Linux-Verteilung zu erhalten, finden Sie Anleitungen zum Exportieren eines Docker-Containers in import any Linux distribution to use with WSL.

Sobald das Tar-Dateiarchiv bereit ist, lesen Sie das Außerkraftsetzung des Verteilungsmanifests , um es lokal auszuprobieren.

Erstellen einer WSL-Dateierweiterung

Der letzte Schritt, nachdem Sie eine TAR-Datei erstellt haben, um Ihre benutzerdefinierte Linux-Verteilung darzustellen, besteht darin, die .tar Dateierweiterung in eine .wsl Dateierweiterung zu ändern, indem Sie sie umbenennen. Durch das Umbenennen dieser Dateierweiterung wird sie als WSL-Verteilung gekennzeichnet. Sobald der TAR umbenannt wurde, .tar .wslwird die Datei unter Windows ordnungsgemäß installiert, wenn sie in Explorer geöffnet (doppelklicken) geöffnet wird. Für diese Doppelklickfunktion ist ein oobe.defaultName Eintrag in der /etc/wsl-distribution.conf Datei erforderlich, um ordnungsgemäß zu funktionieren.

Verteilen der WSL-Verteilung

WSL-Benutzer können verfügbare Verteilungen anzeigen, indem sie ausgeführt wsl --list --online werden, und sie direkt wsl --install <distroName> installieren (ersetzen durch den tatsächlichen Namen der Linux-Verteilung. Dieser Prozess wird durch eine Verteilungsmanifestdatei gesteuert. Sie können diese Manifestdatei zu Ihrer Linux-Verteilung ihres Kunden hinzufügen, damit sie in die wsl --install Befehlsoptionen aufgenommen werden kann.

Die benutzerdefinierte Linux-Distribution TAR, die Sie mit einer .wsl Dateierweiterung erstellt und umbenannt haben, kann jedoch verteilt werden. Nach dem Herunterladen kann ein Benutzer ihn direkt über die Befehlszeile wsl --install --from-file <fileLocation> installieren (ersetzen durch den tatsächlichen Speicherort der Datei). Alternativ kann die Datei für die .wsl benutzerdefinierte WSL-Verteilung geöffnet werden, indem Sie darauf doppelklicken.

Details des Verteilungsmanifests

Das Verteilungsmanifest enthält Metadaten zu den Verteilungen, die für die Installation über wsl --install <distribution>.

TAR-basierte Verteilungen sind unter ModernDistributiondem folgenden Format aufgeführt:

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

Jeder flavor Eintrag enthält eine Liste der installierbaren Verteilungen. Verteilungen können entweder über den Aromanamen (in diesem Fall wird der Standardeintrag installiert) oder den Versionsnamen installiert werden.

Erfahren Sie, wie wsl --install Befehle mit dem folgenden Manifest funktionieren:

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

Beispielinstallationsbefehle:

$ 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

Hinzufügen Ihrer Einführung `wsl --install` für alle WSL-Benutzer

Um Ihre WSL-Distro für alle Benutzer verfügbar zu machen, öffnen Sie eine Pullanforderung im WSL-GitHub-Repository , das die DistributionInfo.json Datei ändert, um Ihre Distroinformationen einzuschließen.

Diese Pullanforderung wird vom WSL-Team überprüft.

Hinzufügen Ihrer Einführung für `wsl --install` Ihr Unternehmen oder Ihre Gruppe

Sie können Ihre Einführung auch nur für eine ausgewählte Gruppe verfügbar wsl --install machen, indem Sie Registrierungsschlüssel auf ausgewählten Computern bearbeiten.

Das WSL-Verteilungsmanifest kann überschrieben werden, indem Registrierungswerte in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss.

DistributionListUrl: Setzt die URL des Verteilungsmanifests außer Kraft.
DistributionListUrlAppend: Hinzufügen von Verteilungen aus dieser Manifest-URL zur Liste der installierbaren Verteilungen

Beide Registrierungswerte sind Zeichenfolgen (REG_SZ) und werden als URL-Format erwartet. Ab WSL 2.4.4 wird das file:// Protokoll unterstützt, um lokale Tests zu vereinfachen. Das erwartete Format lautet: file:///C:/path/to/file

Testen einer lokalen Verteilung

Zum Testen eines Verteilungs-Tars können Sie das folgende PowerShell-Beispielskript verwenden, um das Verteilungsmanifest mit der neuen Verteilung außer Kraft zu setzen. Speichern Sie zuerst das folgende Skript unter 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

Konfigurieren Sie dann das lokale Manifest, indem Sie den folgenden Befehl in einer PowerShell mit erhöhten Rechten ausführen:

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

Nach Abschluss sollte die folgende Ausgabe angezeigt werden: 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

Sie können dann ausführen wsl.exe --install test-distro-v1 , um die Installation der neuen Verteilung zu testen.

Wenn Sie fertig sind, können Sie löschen HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl , um zum offiziellen Manifest zurückzuverwenden.

Bewährte Methoden

Konfigurationsdateien

/etc/wsl.conf und /etc/wsl-distribution.conf sollte einbezogen werden. Sie sollten im Besitz root:root sein, und ihre Berechtigungen sollten 0644
Wenn oobe.command zum Erstellen eines neuen Benutzers verwendet wird, sollte oobe.defaultUid seine UID auf 1000diesen Wert festgelegt werden.
oobe.defaultName und shortcut.icon sollte in /etc/wsl-distribution.conf
/etc/resolv.confsollte nicht in der Stammdateisystem enthalten sein
Es sollte ein Stammbenutzer vorhanden /etc/passwd sein, und seine UID sollte 0
Es sollte kein Kennworthash vorhanden sein /etc/shadow
Das Archiv darf keinen Kernel oder ein Initramfs enthalten.

Systemd

Wenn systemd aktiviert ist, sollten Einheiten, die Probleme mit WSL verursachen können, deaktiviert oder maskiert werden. Die folgenden Einheiten, die bekanntermaßen Probleme in WSL-Verteilungen verursachen (gilt für System- und Benutzereinheiten):

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

Freigeben über

Erstellen einer benutzerdefinierten Linux-Verteilung für WSL

Was sind WSL-Stammdateisystem Tar-Dateien?

Erstellen von WSL-Konfigurationsdateien

Hinzufügen der WSL-Verteilungskonfigurationsdatei

Generieren eines Windows-Terminal Profils

Hinzufügen einer WSL-Konfiguration für lokale Einstellungen pro Verteilung

Erstellen der Tar-Datei

Erstellen einer WSL-Dateierweiterung

Verteilen der WSL-Verteilung

Details des Verteilungsmanifests

Hinzufügen Ihrer Einführung `wsl --install` für alle WSL-Benutzer

Hinzufügen Ihrer Einführung für `wsl --install` Ihr Unternehmen oder Ihre Gruppe

Testen einer lokalen Verteilung

Bewährte Methoden

Konfigurationsdateien

Systemd

Zusätzliche Ressourcen

Freigeben über

Erstellen einer benutzerdefinierten Linux-Verteilung für WSL

Was sind WSL-Stammdateisystem Tar-Dateien?

Erstellen von WSL-Konfigurationsdateien

Hinzufügen der WSL-Verteilungskonfigurationsdatei

Generieren eines Windows-Terminal Profils

Hinzufügen einer WSL-Konfiguration für lokale Einstellungen pro Verteilung

Erstellen der Tar-Datei

Erstellen einer WSL-Dateierweiterung

Verteilen der WSL-Verteilung

Details des Verteilungsmanifests

Hinzufügen Ihrer Einführung wsl --install für alle WSL-Benutzer

Hinzufügen Ihrer Einführung für wsl --install Ihr Unternehmen oder Ihre Gruppe

Testen einer lokalen Verteilung

Bewährte Methoden

Konfigurationsdateien

Systemd

Zusätzliche Ressourcen

Hinzufügen Ihrer Einführung `wsl --install` für alle WSL-Benutzer

Hinzufügen Ihrer Einführung für `wsl --install` Ihr Unternehmen oder Ihre Gruppe