Tworzenie niestandardowej dystrybucji systemu Linux dla programu WSL

Ten przewodnik przeprowadzi cię przez kroki tworzenia i dystrybucji dystrybucji WSL, która jest plikiem .wsl.

Dystrybucje WSL mają dwie części:

1. Główny system plików (dystrybuowany jako plik tar)
2. Wpis manifestu (który zawiera metadane dystrybucji)

Ten przewodnik dotyczy tylko wersji 2.4.4 i nowszej.

Notatka

Zobacz tego repozytorium, aby zapoznać się z poprzednimi instrukcjami dotyczącymi tworzenia pakietów dystrybucji opartych na oprogramowaniu appx.

Co to są pliki tar głównego systemu plików WSL?

Dystrybucje WSL są definiowane przez plik tar z rozszerzeniem pliku .wsl w systemie Windows.

Plik TAR (skrót od Archiwum taśm) to typ pliku archiwum używanego do przechowywania wielu plików razem w jednym pliku w celu łatwiejszej dystrybucji lub tworzenia kopii zapasowej. Plik TAR zawiera główny system plików dystrybucji systemu Linux (wszystkie pliki dystrybucji), a także pliki konfiguracji WSL. Pliki konfiguracji programu WSL informują system operacyjny WIndows, jak zainstalować i uruchomić dystrybucję.

Po utworzeniu systemu Linux, który chcesz przekształcić w dystrybucję WSL, wykonaj poniższe kroki, aby rozpocząć pracę.

Tworzenie plików konfiguracji WSL

Istnieją dwa pliki konfiguracji, które należy uwzględnić w dystrybucji:

1. /etc/wsl-distribution.conf: plik utworzony przez konserwatora dystrybucji odpowiedzialny za kontrolowanie sposobu konfigurowania dystrybucji systemu Linux po pierwszym uruchomieniu z usługą WSL.
2. /etc/wsl.conf: plik zawierający globalne ustawienia systemowe specyficzne dla użytkownika i kontrolujące sposób uruchamiania dystrybucji. dowiedz się więcej o plikach konfiguracji WSL..

Dodawanie pliku konfiguracji dystrybucji WSL

Plik konfiguracji dystrybucji, /etc/wsl-distribution.conf, definiuje sposób konfigurowania dystrybucji systemu Linux po pierwszym uruchomieniu przez użytkownika. Ten plik może służyć do interaktywnego tworzenia konta użytkownika, wyświetlania umowy licencyjnej itp.

Oto przykładowy plik /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

Opcje konfiguracji pliku dystrybucji WSL:

klucz	wartość	domyślny	Notatki
oobe.command	struna	<none>	OOBE oznacza doświadczenie po wyjęciu z pudełka. To polecenie zostaje uruchomione po raz pierwszy, gdy tylko użytkownik otworzy interaktywną powłokę w dystrybucji. Jeśli to polecenie zwróci wartość inną niż zero, zostanie uznane za nieudane, a użytkownik nie będzie mógł otworzyć powłoki.
oobe.defaultUid	liczba całkowita	<none>	Domyślny identyfikator UID, od którego rozpoczyna się dystrybucja. Jest to przydatne, gdy skrypt oobe.command tworzy nowego użytkownika.
oobe.defaultName	struna	<none>	Domyślna nazwa, pod którą zarejestrowano dystrybucję. Tę nazwę domyślną można zastąpić poleceniem: wsl.exe --install <distro> --name <name>
shortcut.icon	struna	Domyślna ikona WSL	Ikona w skrótu menu Start dla dystrybucji. Musi być w formacie .ico o maksymalnym rozmiarze 10MB
shortcut.enabled	typ logiczny (boolowski)	prawdziwy	Czy podczas instalacji dystrybucji należy utworzyć skrót menu Start.
windowsterminal.profileTemplate	struna	<none>	Szablon JSON umożliwiający wygenerowanie profilu terminalu systemu Windows dla tej dystrybucji.
windowsterminal.enabled	typ logiczny (boolowski)	prawdziwy	Czy należy utworzyć profil terminalu podczas instalacji dystrybucji. Jeśli profileTemplate nie zostanie ustawiona, zostanie wygenerowany profil domyślny.
windowsterminal.profileTemplate	struna	Ścieżka do pliku szablonu terminalu	Szablon JSON umożliwiający wygenerowanie profilu terminalu systemu Windows dla tej dystrybucji.

Musisz utworzyć środowisko pierwszego uruchomienia jako gotowe do użycia (OOBE) dla dystrybucji. Poniżej znajduje się przykładowy skrypt bash, którego można użyć. Ten skrypt zakłada, że oobe.defaultUid jest ustawiona na 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

Generowanie profilu terminalu systemu Windows

Program WSL automatycznie generuje profil terminalu systemu Windows po zainstalowaniu dystrybucji. Osoby odpowiedzialne za dystrybucję mogą dostosować wygenerowany profil, ustawiając windowsterminal.profileTemplate w pliku konfiguracji programu WSL, /etc/wsl-distribution.conf.

Plik json jest zgodny z formatem json profilu terminalu. Oto przykładowy 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"
    }
  ]
}

Ten plik nie musi określać profilu namelub commandLine. Są one automatycznie dodawane przez usługę WSL podczas generowania profilu terminalu.

Dodawanie konfiguracji protokołu WSL dla ustawień lokalnych dla poszczególnych dystrybucji

W kontekście głównego systemu plików dystrybucji zalecamy skonfigurowanie ustawień systemd, w tym tego, czy systemd jest domyślnie uruchamiany, w /etc/wsl.conf ustawień lokalnych indywidualnie dla każdej dystrybucji. Zobacz poniższy przykład.

# /etc/wsl.conf

[boot]
systemd=true|false

Autor dystrybucji określa, czy system jest domyślnie włączony, ustawiając wartość boot.systemd na true (włączone) lub false (nie włączono).

Zobacz Zalecenia dla systemd, jeśli domyślnie wybrano opcję włączenia systemd.

Zobacz Konfiguracja ustawień zaawansowanych w WSL, aby uzyskać wszystkie obsługiwane ustawienia w /etc/wsl.conf.

Tworzenie pliku tar

Po utworzeniu plików dystrybucji i konfiguracji główny system plików można przechwycić w pliku tar.

Zalecany sposób tworzenia pliku tar:

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

Katalog główny tar powinien być katalogiem głównym systemu plików (a nie katalogiem zawierającym główny system plików).

Zalecanym formatem kompresji jest gzip. Inne formaty kompresji mogą spowodować niezgodność ze starszymi wersjami WSL.

Zapoznaj się z zaleceniami dotyczącymi plików konfiguracji , aby uzyskać listę plików, które powinny i nie powinny być uwzględnione w konfiguracji.

Aby uzyskać plik tar istniejącej dystrybucji systemu Linux, znajdź wskazówki dotyczące eksportowania kontenera platformy Docker w Importowanie dowolnej dystrybucji systemu Linux do użycia z usługą WSL.

Gdy archiwum plików tar jest gotowe, zobacz Przetestuj dystrybucję lokalnie, aby wypróbować ją lokalnie.

Tworzenie rozszerzenia pliku wsl

Ostatnim krokiem po utworzeniu pliku tar reprezentującego niestandardową dystrybucję systemu Linux jest zmiana rozszerzenia pliku .tar na rozszerzenie pliku .wsl, zmieniając jego nazwę. Zmiana nazwy tego rozszerzenia pliku spowoduje oznaczenie go jako dystrybucji WSL. Po zmianie nazwy tar z .tar na .wslplik zostanie poprawnie zainstalowany w systemie Windows po otwarciu (dwukrotnie kliknięty) w Eksploratorze plików. Wpis oobe.defaultName jest wymagany w pliku /etc/wsl-distribution.conf, aby funkcja dwukrotnego kliknięcia działała prawidłowo.

Rozprowadź swoją dystrybucję WSL

Użytkownicy programu WSL mogą wyświetlać dostępne dystrybucje, uruchamiając wsl --list --online i mogą instalować je bezpośrednio przy użyciu wsl --install <distroName> (zastępując <distroName> rzeczywistą nazwą dystrybucji systemu Linux. Ten proces jest kontrolowany przez plik manifestu dystrybucji. Ten plik manifestu można dodać do dystrybucji systemu Linux klienta, aby został uwzględniony w opcjach poleceń wsl --install.

Niestandardowa dystrybucja Linux w formacie tar, którą utworzono i której rozszerzenie zmieniono na .wsl, może być dystrybuowana według uznania. Po pobraniu użytkownik może zainstalować go bezpośrednio z wiersza polecenia za pomocą wsl --install --from-file <fileLocation> (zastępując <fileLocation> rzeczywistą lokalizacją pliku). Alternatywnie można otworzyć plik .wsl dla niestandardowej dystrybucji WSL, klikając go dwukrotnie.

Szczegóły manifestu dystrybucji

Manifest dystrybucji zawiera metadane dotyczące dystrybucji dostępnych do instalacji za pośrednictwem wsl --install <distribution>.

Dystrybucje systemu Linux, które są oparte na tarie, są wymienione w ModernDistribution, z poniższym formatem:

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

Każdy wpis flavor zawiera listę instalowanych dystrybucji. Dystrybucje można zainstalować poprzez nazwę wersji typu (w takim przypadku instalowana jest domyślna wersja) lub nazwę wersji.

Zobacz, jak działają polecenia wsl --install na poniższym manifeście:

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

Przykładowe polecenia instalacji:

$ 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

Dodawanie dystrybucji do wsl --install dla wszystkich użytkowników programu WSL

Aby udostępnić dystrybucję WSL wszystkim użytkownikom, otwórz żądanie ściągnięcia w repozytorium GitHub WSL, które modyfikuje plik DistributionInfo.json w celu uwzględnienia informacji o dystrybucji.

To żądanie ściągnięcia zostanie przejrzyone przez zespół WSL.

Dodawanie dystrybucji do wsl --install dla przedsiębiorstwa lub grupy biznesowej

Dystrybucję można również udostępnić w wsl --install tylko do wybranej grupy, edytując klucze rejestru na wybranych urządzeniach z systemem Windows.

Manifest dystrybucji WSL może zostać zastąpiony przez utworzenie wartości rejestru w HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss.

• DistributionListUrl: zastępuje adres URL manifestu dystrybucji
• DistributionListUrlAppend: Dodaj dystrybucje z tego adresu URL manifestu do listy dystrybucji możliwych do zainstalowania

Obie wartości rejestru to ciągi (REG_SZ) i powinny być w formacie adresu URL.

Począwszy od wersji WSL 2.4.4, protokół file:// jest obsługiwany w celu ułatwienia lokalnego testowania. Oczekiwany format to: file:///C:/path/to/file.

Testowanie dystrybucji lokalnie

Aby przetestować plik tar dystrybucji, możesz użyć następującego przykładowego skryptu programu PowerShell, aby zastąpić manifest dystrybucji nowym plikiem. Najpierw zapisz poniższy skrypt jako 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 

Następnie skonfiguruj manifest lokalny, uruchamiając następujące polecenie w programie PowerShell z podwyższonym poziomem uprawnień:

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

Po zakończeniu powinny zostać wyświetlone następujące dane wyjściowe z 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

Następnie możesz uruchomić wsl.exe --install test-distro-v1, aby spróbować zainstalować nową dystrybucję.

Gdy skończysz, możesz usunąć HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl, aby przywrócić oficjalny manifest.

Zalecenia dotyczące niestandardowej dystrybucji systemu Linux w programie WSL

Zalecenia dotyczące pliku konfiguracji

• Upewnij się, że dystrybucja niestandardowa zawiera pliki konfiguracji /etc/wsl.conf i /etc/wsl-distribution.conf. Oba pliki powinny być własnością root:root, a ich uprawnienia powinny być 0644.
• Jeśli ustawienie oobe.command jest używane do tworzenia nowego użytkownika, należy ustawić zarówno uid, jak i oobe.defaultUid na wartość 1000.
• Upewnij się, że w pliku konfiguracji dystrybucji ustawiono zarówno oobe.defaultName, jak i shortcut.icon: /etc/wsl-distribution.conf
• Nie dołączaj pliku /etc/resolv.conf do głównego katalogu systemu plików.
• Dołącz użytkownika root do /etc/passwd. Dla tego użytkownika głównego (root) wartość uid powinna być 0.
• W /etc/shadownie powinny istnieć skróty haseł.
• Archiwum nie powinno zawierać jądra ani initramfs.

Zalecenia systemowe

Jeśli systemd jest włączony, jednostki, które mogą powodować problemy z usługą WSL, powinny być wyłączone lub maskowane. Poniższe jednostki są znane z powodowania problemów w dystrybucjach WSL (dotyczy zarówno jednostek systemowych, jak i użytkownika):

• 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