Freigeben über

Erstellen einer benutzerdefinierten Linux-Verteilung für WSL

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:

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

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:

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

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

Konfigurationsoptionen für WSL-Verteilungsdateien:

Schlüssel Wert Standardeinstellung 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
shortcut.enabled Boolescher Wert Wahr Gibt an, ob beim Installieren der Verteilung eine Startmenüverknüpfung erstellt werden soll.
windowsterminal.profileTemplate Zeichenfolge <none> Die JSON-Vorlage zum Generieren eines Windows-Terminal Profils für diese Verteilung.
windowsterminal.enabled Boolescher Wert Wahr Gibt an, ob beim Installieren der Verteilung ein Terminalprofil erstellt werden soll. Wenn profileTemplate nicht gesetzt ist, wird ein Standardprofil erstellt.
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/sbin/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 namedas Profil commandLinenicht 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.

Sehen Sie sich die Systemd-Empfehlungen an , wenn Sie das System standardmäßig aktiviert haben.

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 das Stammdateisystem in der Tar-Datei erfasst werden.

Die empfohlene Methode zum Erstellen der Tar-Datei:

$ 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.

Eine Liste der Dateien, die nicht in der Konfiguration enthalten sein sollten, finden Sie in den Empfehlungen zur Konfigurationsdatei .

Um eine Tar-Datei einer vorhandenen Linux-Distribution zu erhalten, finden Sie Anleitungen zum Exportieren eines Docker-Containers im Abschnitt Importieren einer beliebigen Linux-Distribution zur Verwendung mit WSL.

Sobald das Tar-Dateiarchiv bereit ist, lesen Sie "Testen der Verteilung lokal ", 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 das Tar von .tar in .wsl umbenannt wurde, wird die Datei ordnungsgemäß unter Windows installiert, wenn sie im Windows Explorer geöffnet (doppelt geklickt) wird. Für diese Doppelklickfunktion ist ein Eintrag in der oobe.defaultName Datei erforderlich, damit sie ordnungsgemäß funktioniert.

Verteilen der WSL-Verteilung

WSL-Benutzer können verfügbare Distributionen anzeigen, indem sie wsl --list --online ausführen, und sie direkt mit wsl --install <distroName> installieren (ersetzen Sie <distroName> durch den tatsächlichen Namen der Linux-Distribution). 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.

Ein benutzerdefiniertes Linux-Distributionsarchiv, das Sie erstellt und mit einer .wsl Dateierweiterung umbenannt haben, kann nach Belieben verteilt werden. Nach dem Herunterladen kann ein Benutzer ihn direkt über die Befehlszeile wsl --install --from-file <fileLocation> installieren (ersetzen <fileLocation> 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>.

Linux-Distributionen, die tarbasiert sind, werden unter ModernDistribution, mit dem 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 Distribution zu wsl --install für alle WSL-Benutzer.

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

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

Hinzufügen Ihres Vertriebskanals zu wsl --install für Ihr Unternehmen oder Ihre Unternehmensgruppe

Sie können Ihre Verteilung auch nur für eine ausgewählte Gruppe wsl --install verfügbar machen, indem Sie Registrierungsschlüssel auf ausgewählten Windows-Geräten 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 Release 2.4.4 wird das file:// Protokoll unterstützt, um lokale Tests zu vereinfachen. Das erwartete Format lautet: file:///C:/path/to/file.

Lokales Testen der 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

Sobald die Aufgabe abgeschlossen ist, sollte die folgende Ausgabe von wsl.exe --list --online angezeigt werden:

$ 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.

Empfehlungen für benutzerdefinierte Linux-Distributionen für WSL

Empfehlungen für Konfigurationsdateien

  • Stellen Sie sicher, dass Ihre benutzerdefinierte Verteilung sowohl die Dateien /etc/wsl.conf als auch die /etc/wsl-distribution.conf Konfigurationsdateien enthält. Beide Dateien sollten im Besitz root:root sein, und ihre Berechtigungen sollten sein 0644.
  • Wenn die oobe.command Einstellung verwendet wird, um einen neuen Benutzer zu erstellen, sollten sowohl uid als auch oobe.defaultUid auf 1000 festgelegt werden.
  • Stellen Sie sicher, dass Sie sowohl oobe.defaultName als auch shortcut.icon in der Verteilungskonfigurationsdatei festlegen: /etc/wsl-distribution.conf
  • Schließen Sie die Datei /etc/resolv.conf nicht in das Stammdateisystem ein.
  • Schließen Sie einen Stammbenutzer in /etc/passwdein. Der uid für diesen Stammbenutzer sollte 0 sein.
  • Es sollte kein Kennworthash in /etc/shadow vorhanden sein.
  • Das Archiv darf keinen Kernel oder ein Initramfs enthalten.

Systemierte Empfehlungen

Wenn systemd aktiviert ist, sollten Einheiten, die Probleme mit WSL verursachen können, deaktiviert oder maskiert werden. Die unten aufgeführten Units sind bekannt dafür, Probleme in WSL-Distributionen zu verursachen (gilt sowohl für System- als auch für 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