Dela via

Skapa en anpassad Linux-distribution för WSL

Den här guiden går igenom stegen för att skapa och distribuera en WSL-distribution, vilket är en .wsl fil.

WSL-distributioner har två delar:

  1. Ett rotfilsystem (distribuerat som en tar-fil)
  2. En manifestpost (som innehåller distributionsmetadata)

Den här guiden gäller endast för WSL version 2.4.4 och senare.

Anmärkning

Se den här lagringsplatsen för föregående appx-baserade distributionspaketeringsinstruktioner.

Vad är tar-filer för WSL-rotfilsystem?

WSL-distributioner definieras av en tar-fil med ett .wsl filnamnstillägg i Windows.

En TAR-fil (förkortning för Bandarkiv) är en typ av arkivfil som används för att lagra flera filer tillsammans i en enda fil för enklare distribution eller säkerhetskopiering. TAR-filen innehåller rotfilsystemet för en Linux-distribution (alla distributionsfiler) samt WSL-konfigurationsfilerna. WSL-konfigurationsfiler talar om för WIndows-operativsystemet hur du installerar och startar distributionen.

När du har ett Linux-system som du vill göra i en WSL-distribution följer du stegen nedan för att komma igång.

Skapa WSL-konfigurationsfiler

Det finns två konfigurationsfiler som distributionen bör innehålla:

  1. /etc/wsl-distribution.conf: En fil som skapats av den distributionsunderhållare som ansvarar för att styra hur Linux-distributionen ska konfigureras när den först startas med WSL.
  2. /etc/wsl.conf: En fil som innehåller globala systeminställningar som är specifika för användaren och styr hur distributionen startas. Läs mer om WSL-konfigurationsfiler..

Lägg till konfigurationsfilen för WSL-distribution

Distributionskonfigurationsfilen, /etc/wsl-distribution.conf, definierar hur Linux-distributionen ska konfigureras när användaren först startar. Den här filen kan användas för att interaktivt skapa ett användarkonto, visa ett licensavtal osv.

Här är ett exempel på en /etc/wsl-distribution.conf fil:

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

Konfigurationsalternativ för WSL-distributionsfil:

Nyckel Värde Förinställning Noteringar
oobe.command sträng Ingen OOBE står för out of box-upplevelsen. Det här kommandot körs första gången användaren öppnar ett interaktivt gränssnitt i distributionen. Om kommandot returnerar något annat än noll anses det vara misslyckat, och användaren kommer inte att kunna öppna en shell.
oobe.defaultUid heltal Ingen Standard-UID:et som fördelningen börjar med. Detta är användbart när skriptet oobe.command skapar en ny användare.
oobe.defaultName sträng Ingen Standardnamnet som fördelningen är registrerad under. Det här standardnamnet kan ersättas med kommandot: wsl.exe --install <distro> --name <name>
shortcut.icon sträng Standardikonen för WSL Ikonen i genvägen i Start-menyn för distributionen. Måste vara i .ico format med en maximal storlek på 10MB
shortcut.enabled boolesk sann Om en genväg till Start-menyn ska skapas när distributionen installeras.
windowsterminal.profileTemplate sträng Ingen JSON-mallen för att generera en Windows Terminal-profil för den här distributionen.
windowsterminal.enabled boolesk sann Om en terminalprofil ska skapas när distributionen installeras. Om profileTemplate inte har angetts genereras en standardprofil.
windowsterminal.profileTemplate sträng Sökväg till en terminalmallfil JSON-mallen för att generera en Windows Terminal-profil för den här distributionen.

Du måste skapa en out of box-upplevelse (OOBE) första körningsupplevelse för distributionen. Nedan visas ett bash-exempelskript som du kan använda. Det här skriptet förutsätter att oobe.defaultUid är inställt på 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

Generera en Windows Terminal-profil

WSL genererar automatiskt en Windows Terminal-profil när en distribution installeras. Distributionsunderhållare kan anpassa den genererade profilen som genereras genom att ange windowsterminal.profileTemplate i WSL-konfigurationsfilen /etc/wsl-distribution.conf.

Json-filen följer json-formatet för terminalprofilen. Här är en exempelprofil:

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

Den här filen behöver inte ange profilen nameeller commandLine. De läggs automatiskt till av WSL när terminalprofilen genereras.

Lägga till en WSL-konfiguration för lokala inställningar per distribution

I samband med ett distributionsrotfilsystem rekommenderar vi att du konfigurerar systembaserade inställningar, inklusive om systemd startar som standard, i /etc/wsl.conf lokala inställningarna per distribution. Se exemplet nedan.

# /etc/wsl.conf

[boot]
systemd=true|false

Distributionsförfattaren avgör om systemd är aktiverat som standard genom att ange det boot.systemd värdet till true (aktiverat) eller false (inte aktiverat).

Se Systemd-rekommendationer om du väljer att aktivera systemd som standard.

Se Konfiguration av avancerade inställningar i WSL- för alla inställningar som stöds i /etc/wsl.conf.

Skapa tar-filen

När distributions- och konfigurationsfilerna är på plats kan rotfilsystemet samlas in i tar-filen.

Det rekommenderade sättet att skapa tar-filen:

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

Roten för tar-arkivet ska vara roten av filsystemet (inte en katalog som innehåller själva rotfilsystemet).

Det rekommenderade komprimeringsformatet är gzip. Andra komprimeringsformat riskerar att bryta kompatibiliteten med äldre WSL-versioner.

Se rekommendationer för konfigurationsfiler för en lista över filer som ska och inte bör ingå i konfigurationen.

Om du vill hämta en tar-fil för en befintlig Linux-distribution kan du få vägledning om hur du exporterar en Docker-container i Importera en Linux-distribution som ska användas med WSL.

När tar-filarkivet är klart kan du läsa Testa distributionen lokalt för att testa den lokalt.

Skapa filnamnstillägget .wsl

Det sista steget, när du har skapat en tar-fil som representerar din anpassade Linux-distribution, är att ändra .tar filnamnstillägget till ett .wsl filnamnstillägg genom att byta namn på det. Om du byter namn på filnamnstillägget markeras det som en WSL-distribution. När tar-filen har bytt namn från .tar till .wslinstalleras filen korrekt i Windows när den öppnas (dubbelklickas) i Windows Utforskaren. Ett oobe.defaultName-inlägg krävs i /etc/wsl-distribution.conf-filen för att dubbelklicksupplevelsen ska fungera korrekt.

Distribuera ditt WSL-distribution

WSL-användare kan visa tillgängliga distributioner genom att köra wsl --list --online och kan installera dem direkt med wsl --install <distroName> (ersätta <distroName> med det faktiska namnet på Linux-distributionen. Den här processen styrs av en distributionsmanifestfil. Du kan lägga till den här manifestfilen i din linux-kunddistribution för att den ska ingå i wsl --install kommandoalternativ.

Den anpassade Linux-distributionens tar-arkiv som du har skapat och bytt namn på med en .wsl-filändelse kan distribueras på det sätt du vill. När en användare har laddat ned den kan den installeras direkt från kommandoraden med wsl --install --from-file <fileLocation> (ersätta <fileLocation> med filens faktiska plats). Du kan också öppna den .wsl filen för din anpassade WSL-distribution genom att dubbelklicka på den.

Information om distributionsmanifest

-distributionsmanifestet innehåller metadata om de distributioner som är tillgängliga för installation via wsl --install <distribution>.

Linux-distributioner som är tar-baserade visas under ModernDistribution, med formatet nedan:

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

Varje flavor post innehåller en lista över installationsbara distributioner. Distributioner kan installeras antingen via variantnamnet (i så fall installeras standardposten) eller versionsbeteckningen.

Se hur wsl --install kommandon fungerar med manifestet nedan:

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

Exempel på installationskommandon:

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

Lägga till din distribution i wsl --install för alla WSL-användare

För att distributionen ska inkluderas i listan för kommandot: wsl --list --onlinemåste distributionen uppfylla de medlemskapsvillkor som beskrivs i distributionsutskickslistan. Detta säkerställer att alla listade distributioner följer de nödvändiga säkerhetsstandarderna.

Om distributionen uppfyller kriterierna och du vill lägga till den i --install listan skickar du en pull-begäran på WSL GitHub-lagringsplatsen (https://github.com/microsoft/WSL) som uppdaterar DistributionInfo.json-filen med din distributionsinformation. Den här pull-begäran granskas av WSL-teamet.

Lägga till din distribution för din företags- eller affärsgrupp i wsl --install

Du kan också göra distributionen tillgänglig i wsl --install endast till en utvald grupp genom att redigera registernycklar på de valda Windows-enheterna.

WSL-distributionsmanifestet kan åsidosättas genom att skapa registervärden i HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss.

  • DistributionListUrl: Åsidosätter distributionsmanifestets URL
  • DistributionListUrlAppend: Lägg till distributioner från manifest-URL:en till listan över installationsbara distributioner

Båda registervärdena är strängar (REG_SZ) och förväntas vara i URL-format.

Från och med WSL version 2.4.4 stöds file://-protokollet för att göra lokal testning enklare. Det förväntade formatet är: file:///C:/path/to/file.

Testa distributionen lokalt

För att testa en tar-fil för distribution kan du använda följande PowerShell-exempelskript för att ersätta distributionsmanifestet med den nya distributionen. Spara först skriptet nedan som 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

Konfigurera sedan det lokala manifestet genom att köra följande kommando i en upphöjd PowerShell:

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

När du är klar bör du se följande utdata från 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

Du kan sedan köra wsl.exe --install test-distro-v1 för att prova installationen av den nya distributionen.

När du är klar kan du ta bort HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl för att återgå till det officiella manifestet.

Rekommendationer för anpassad Linux-distribution i WSL

Rekommendationer för konfigurationsfiler

  • Se till att din anpassade distribution innehåller både /etc/wsl.conf- och /etc/wsl-distribution.conf konfigurationsfilerna. Båda filerna ska ägas av root:root och deras behörigheter ska vara 0644.
  • Om inställningen oobe.command används för att skapa en ny användare ska både uid och oobe.defaultUid anges till 1000.
  • Se till att du anger både oobe.defaultName och shortcut.icon i distributionskonfigurationsfilen: /etc/wsl-distribution.conf
  • Ta inte med filen /etc/resolv.conf i rotfilsystemet.
  • Inkludera en administratörsanvändare i /etc/passwd. uid för den här rotanvändaren ska vara 0.
  • Det ska inte finnas några lösenordshashvärden i /etc/shadow.
  • Arkivet får inte innehålla en kernel eller initramfs.

Systemrekommendationer

Om systemd är aktiverat bör enheter som kan orsaka problem med WSL inaktiveras eller maskeras. Enheterna nedan är kända för att orsaka problem i WSL-distributioner (gäller både system- och användarenheter):

  • 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
  • Last updated on