Een aangepaste Linux-distributie bouwen voor WSL

In deze handleiding worden de stappen beschreven voor het maken en distribueren van een WSL-distributie. Dit is een .wsl-bestand.

WSL-distributies hebben twee delen:

1. Een hoofdbestandssysteem (gedistribueerd als tar-bestand)
2. Een manifestvermelding (die de distributiemetagegevens bevat)

Deze handleiding is alleen van toepassing op WSL-release 2.4.4 en hoger.

Wat zijn tar-bestanden van het WSL-hoofdbestandssysteem?

WSL-distributies worden gedefinieerd door een tar-bestand met een .wsl bestandsextensie in Windows.

Een TAR-bestand (afkorting voor Tape Archive) is een type archiefbestand dat wordt gebruikt om meerdere bestanden samen op te slaan in één bestand voor eenvoudigere distributie of back-up. Het TAR-bestand bevat het hoofdbestandssysteem van een Linux-distributie (alle distributiebestanden), evenals de WSL-configuratiebestanden. WSL-configuratiebestanden vertellen het besturingssysteem WIndows hoe de distributie moet worden geïnstalleerd en gestart.

Zodra u een Linux-systeem hebt dat u in een WSL-distributie wilt maken, volgt u de onderstaande stappen om aan de slag te gaan.

WSL-configuratiebestanden maken

Er zijn twee configuratiebestanden die de distributie moet bevatten:

1. /etc/wsl-distribution.conf: een bestand dat is gemaakt door de distributieonderhouder die verantwoordelijk is voor het beheren van de wijze waarop de Linux-distributie moet worden geconfigureerd bij de eerste lancering met WSL.
2. /etc/wsl.conf: een bestand met algemene systeeminstellingen die specifiek zijn voor de gebruiker en bepalen hoe de distributie wordt gestart. Meer informatie over WSL-configuratiebestanden..

Het WSL-distributieconfiguratiebestand toevoegen

Het distributieconfiguratiebestand, /etc/wsl-distribution.conf, definieert hoe de Linux-distributie moet worden geconfigureerd wanneer deze voor het eerst door de gebruiker wordt gestart. Dit bestand kan worden gebruikt om interactief een gebruikersaccount te maken, een gebruiksrechtovereenkomst weer te geven, enzovoort.

Hier volgt een voorbeeldbestand /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

Configuratieopties voor WSL-distributiebestanden:

U moet een out-of-boxervaring (OOBE) creëren voor de eerste keer dat de distributie wordt uitgevoerd. Hieronder ziet u een voorbeeld van een bash-script dat u kunt gebruiken. In dit script wordt ervan uitgegaan dat oobe.defaultUid is ingesteld op 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

Een Windows Terminal-profiel genereren

WSL genereert automatisch een Windows Terminal-profiel wanneer een distributie is geïnstalleerd. Distributieonderhouders kunnen het gegenereerde profiel aanpassen door windowsterminal.profileTemplate in het WSL-configuratiebestand in te stellen /etc/wsl-distribution.conf.

Het json-bestand volgt de json-indeling van het terminalprofiel. Hier volgt een voorbeeldprofiel:

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

Dit bestand hoeft het profiel niet op te geven nameof commandLine. Deze worden automatisch toegevoegd door WSL bij het genereren van het terminalprofiel.

Een WSL-configuratie toevoegen voor lokale instellingen per distributie

In de context van een distributie-root-bestandssysteem raden we aan om de systemd-instellingen te configureren, inclusief of systemd standaard start, in de /etc/wsl.conf lokale instellingen per distributie. Zie het onderstaande voorbeeld.

# /etc/wsl.conf

[boot]
systemd=true|false

De distributieauteur bepaalt of systemd standaard is ingeschakeld door de boot.systemd waarde in te stellen op true (ingeschakeld) of false (niet ingeschakeld).

Zie de aanbevelingen voor Systemd als u ervoor hebt gekozen om systemd standaard in te schakelen.

Zie geavanceerde instellingenconfiguratie in WSL voor alle ondersteunde instellingen in /etc/wsl.conf.

Het tar-bestand maken

Zodra de distributie- en configuratiebestanden zijn ingesteld, kan het hoofdbestandssysteem worden vastgelegd in het tar-bestand.

De aanbevolen manier om het tar-bestand te maken:

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

De hoofdmap van de tar moet de hoofdmap van het bestandssysteem zijn (niet een map die het hoofdbestandssysteem bevat).

De aanbevolen compressieindeling is gzip. Andere compressieindelingen lopen het risico dat compatibiliteit met oudere WSL-versies wordt onderbroken.

Zie de aanbevelingen voor configuratiebestanden voor een lijst met bestanden die niet in de configuratie moeten worden opgenomen.

Als u een tar-bestand van een bestaande Linux-distributie wilt verkrijgen, raadpleegt u richtlijnen voor het exporteren van een Docker-container in Importeert u een Linux-distributie die moet worden gebruikt met WSL-.

Zodra het tar-bestandarchief gereed is, raadpleegt u De distributie lokaal testen om het lokaal uit te proberen.

Een .wsl-bestandsextensie maken

De laatste stap, wanneer u een tar-bestand hebt gemaakt om uw aangepaste Linux-distributie weer te geven, is het wijzigen van de .tar bestandsextensie in een .wsl bestandsextensie door de naam ervan te wijzigen. Als u de naam van deze bestandsextensie wijzigt, wordt deze gemarkeerd als een WSL-distributie. Zodra de naam van het tar-bestand is gewijzigd van .tar naar .wsl, wordt het bestand correct geïnstalleerd in Windows wanneer het wordt geopend door te dubbelklikken in Verkenner. Een oobe.defaultName vermelding is vereist in het /etc/wsl-distribution.conf bestand om deze dubbelklik-functionaliteit correct te laten werken.

Verspreid uw WSL-distributie

WSL-gebruikers kunnen beschikbare distributies bekijken door wsl --list --online uit te voeren en ze rechtstreeks met wsl --install <distroName> te installeren (waarbij <distroName> wordt vervangen door de werkelijke naam van de Linux-distributie. Dit proces wordt beheerd door een distributiemanifestbestand. U kunt dit manifestbestand toevoegen aan de Linux-distributie van uw klant zodat het kan worden opgenomen in de wsl --install opdrachtopties.

De aangepaste Linux-distributie tar die u hebt gemaakt en hernoemd met een .wsl bestandsextensie, kan naar eigen inzicht worden gedistribueerd. Zodra een bestand is gedownload, kan de gebruiker het rechtstreeks vanaf de opdrachtregel installeren met wsl --install --from-file <fileLocation> (waarbij <fileLocation> wordt vervangen door de werkelijke locatie van het bestand). U kunt ook het .wsl-bestand voor uw aangepaste WSL-distributie openen door erop te dubbelklikken.

Details van distributiemanifest

Het distributiemanifest bevat metagegevens over de distributies die beschikbaar zijn voor installatie via wsl --install <distribution>.

Linux-distributies die zijn gebaseerd op tar worden vermeld onder ModernDistribution, met de onderstaande indeling:

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

Elke flavor vermelding bevat een lijst met installeerbare distributies. Distributies kunnen worden geïnstalleerd via de variantnaam (in welk geval de standaardinstelling wordt geïnstalleerd) of de versienaam.

Bekijk hoe wsl --install opdrachten werken met het onderstaande manifest:

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

Voorbeeld van installatieopdrachten:

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

Uw distributie toevoegen aan wsl --install voor alle WSL-gebruikers

Als u de distributie wilt opnemen in de lijst voor de opdracht: wsl --list --online, moet de distributie voldoen aan de lidmaatschapscriteria die in de distributieadreslijst worden beschreven. Dit zorgt ervoor dat alle vermelde distributies voldoen aan de benodigde beveiligingsstandaarden.

Als uw distributie voldoet aan de criteria en u deze wilt toevoegen aan de --install lijst, dient u een pull-aanvraag in in de WSL GitHub-opslagplaats (https://github.com/microsoft/WSL) waarmee het DistributionInfo.json bestand wordt bijgewerkt met de details van uw distributie. Deze pull-aanvraag wordt beoordeeld door het WSL-team.

Uw distributie toevoegen aan wsl --install voor uw onderneming of bedrijfsgroep

U kunt uw distributie ook beschikbaar maken in wsl --install alleen voor een bepaalde groep door registersleutels te bewerken op de gekozen Windows-apparaten.

Het WSL-distributiemanifest kan worden overschreven door waarden in het register aan te maken in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss.

• DistributionListUrl: hiermee wordt de URL van het distributiemanifest overschreven
• DistributionListUrlAppend: Distributies uit die manifest-URL toevoegen aan de lijst met geïnstalleerde distributies

Beide registerwaarden zijn tekenreeksen (REG_SZ) en hebben naar verwachting de URL-indeling.

Vanaf WSL-release 2.4.4 wordt het file://-protocol ondersteund om lokale tests eenvoudiger te maken. De verwachte indeling is: file:///C:/path/to/file.

De distributie lokaal testen

Als u een distributieteer wilt testen, kunt u het volgende PowerShell-voorbeeldscript gebruiken om het distributiemanifest te overschrijven met de nieuwe distributie. Sla eerst het onderstaande script op als 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

Configureer vervolgens het lokale manifest door de volgende opdracht uit te voeren in een PowerShell met verhoogde bevoegdheid:

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

Zodra dit is voltooid, ziet u de volgende uitvoer van 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

Vervolgens kunt u wsl.exe --install test-distro-v1 uitvoeren om de installatie van de nieuwe distributie uit te voeren.

Wanneer u klaar bent, kunt u HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl verwijderen om terug te keren naar het officiële manifest.

Aanbevelingen voor aangepaste Linux-distributie in WSL

Aanbevelingen voor configuratiebestanden

• Zorg ervoor dat uw aangepaste distributie zowel de /etc/wsl.conf als /etc/wsl-distribution.conf configuratiebestanden bevat. Beide bestanden moeten eigendom zijn van root:root en hun machtigingen moeten worden 0644.
• Als de oobe.command-instelling wordt gebruikt om een nieuwe gebruiker te maken, moeten zowel uid als oobe.defaultUid worden ingesteld op 1000.
• Zorg ervoor dat u zowel oobe.defaultName als shortcut.icon instelt in het distributieconfiguratiebestand: /etc/wsl-distribution.conf
• Neem bestand /etc/resolv.conf niet op in het hoofdbestandssysteem.
• Voeg een rootgebruiker toe in /etc/passwd. De uid voor deze hoofdgebruiker moet worden 0.
• Er mogen geen wachtwoordhashes in /etc/shadowzijn.
• Het archief mag geen kernel of een initramfs bevatten.

Aanbevelingen voor Systemd

Als systemd is ingeschakeld, moeten eenheden die problemen met WSL kunnen veroorzaken, worden uitgeschakeld of gemaskeerd. De onderstaande eenheden zijn bekend om problemen in WSL-distributies te veroorzaken (van toepassing op zowel systeem- als gebruikerseenheden):

• 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