Vytvoření vlastní distribuce Linuxu pro WSL

Tento průvodce vás provede postupem vytvoření a distribuce distribuce WSL, což je soubor .wsl.

Distribuce WSL mají dvě části:

Kořenový systém souborů (distribuovaný jako soubor tar)
Položka manifestu (která obsahuje metadata distribuce)

Tato příručka platí jenom pro WSL verze 2.4.4 a vyšší.

Poznámka

Viz toto úložiště pro předchozí pokyny k balení distribuce založené na appxu.

Co jsou soubory tar systému kořenových souborů WSL?

Distribuce WSL jsou definovány tar souborem s příponou .wsl v systému Windows.

Soubor TAR (zkratka pro Páskový archiv) je typ archivního souboru sloužícího k uložení více souborů do jednoho souboru pro snadnější distribuci nebo zálohování. Soubor TAR obsahuje kořenový systém souborů linuxové distribuce (všechny distribuční soubory) a konfigurační soubory WSL. Konfigurační soubory WSL říkají operačnímu systému WIndows, jak nainstalovat a spustit distribuci.

Jakmile máte systém Linux, který chcete provést v distribuci WSL, postupujte podle následujících kroků a začněte.

Vytvoření konfiguračních souborů WSL

Distribuce by měla obsahovat dva konfigurační soubory:

/etc/wsl-distribution.conf: Soubor vytvořený správcem distribuce zodpovědný za řízení způsobu konfigurace distribuce v Linuxu při prvním spuštění pomocí WSL.
/etc/wsl.conf: Soubor obsahující globální nastavení systému, které jsou specifické pro uživatele a řídí způsob spuštění distribuce. Další informace o konfiguračních souborech WSL..

Přidání konfiguračního souboru distribuce WSL

Konfigurační soubor distribuce, /etc/wsl-distribution.conf, definuje, jak má být distribuce Linuxu nakonfigurována při prvním spuštění uživatelem. Tento soubor lze použít k interaktivnímu vytvoření uživatelského účtu, zobrazení licenční smlouvy atd.

Tady je ukázkový soubor /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

Možnosti konfigurace distribučního souboru WSL:

Klíč	Hodnota	Výchozí	Poznámky
`oobe.command`	řetězec	Žádné	OOBE je zkratka pro zážitek okamžitě po vybalení. Tento příkaz se spustí při prvním otevření interaktivního prostředí v distribuci. Pokud tento příkaz vrátí nenulovou hodnotu, považuje se za neúspěšný, a uživatel nebude moct otevřít příkazovou řádku.
`oobe.defaultUid`	integer	Žádné	Výchozí UID, se kterým distribuce začíná. To je užitečné, když `oobe.command` skript vytvoří nového uživatele.
`oobe.defaultName`	řetězec	Žádné	Výchozí název, pod kterým je distribuce zaregistrovaná. Tento výchozí název lze nahradit příkazem: `wsl.exe --install <distro> --name <name>`
`shortcut.icon`	řetězec	Výchozí ikona WSL	Ikona v místní nabídce Start pro distribuci. Musí být ve formátu `.ico` s maximální velikostí `10MB`
`shortcut.enabled`	booleovský	pravda	Zda má být vytvořena zkratka v nabídce Start při instalaci distribuce.
`windowsterminal.profileTemplate`	řetězec	Žádné	Šablona JSON pro vygenerování profilu terminálu Windows pro tuto distribuci.
`windowsterminal.enabled`	booleovský	pravda	Určuje, jestli se má profil terminálu vytvořit při instalaci distribuce. Pokud `profileTemplate` není nastavená, vygeneruje se výchozí profil.
`windowsterminal.profileTemplate`	řetězec	Cesta k souboru šablony terminálu	Šablona JSON pro vygenerování profilu terminálu Windows pro tuto distribuci.

Pro distribuci je potřeba vytvořit zážitek bezprostředního používání při prvním spuštění (OOBE). Níže je ukázkový skript Bash, který můžete použít. Tento skript předpokládá, že oobe.defaultUid je nastavená 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

Vygenerování profilu terminálu Windows

WSL automaticky vygeneruje profil terminálu Systému Windows při instalaci distribuce. Správci distribuce mohou upravit vygenerovaný profil vygenerovaný nastavením windowsterminal.profileTemplate v konfiguračním souboru WSL /etc/wsl-distribution.conf.

Soubor JSON se řídí formátu JSON profilu terminálu. Tady je příklad profilu:

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

Tento soubor nemusí specifikovat profil nameani commandLine. Ty se při generování profilu terminálu automaticky přidají službou WSL.

Přidejte konfiguraci WSL pro místní nastavení pro každou distribuci

V kontextu kořenového souborového systému distribuce doporučujeme nakonfigurovat nastavení systemd, včetně toho, zda se systemd spouští ve výchozím nastavení, v místním nastavení /etc/wsl.conf pro jednotlivé distribuce. Podívejte se na následující příklad.

# /etc/wsl.conf

[boot]
systemd=true|false

Autor distribuce určuje, zda je systém ve výchozím nastavení povolen nastavením hodnoty boot.systemd na true (povoleno) nebo false (není povoleno).

Pokud jste se rozhodli povolit systemd ve výchozím nastavení, podívejte se na doporučení pro Systemd .

Podrobnosti o všech podporovaných nastaveních najdete v části Konfigurace pokročilých nastavení pro WSL v rámci /etc/wsl.conf.

Vytvoření souboru tar

Po umístění distribučních a konfiguračních souborů lze kořenový systém souborů zachytit v souboru tar.

Doporučený způsob vytvoření souboru tar:

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

Kořen tar by měl být kořenem systému souborů (nikoli adresář obsahující kořenový systém souborů).

Doporučený formát komprese je gzip. Jiné formáty komprese riskují porušení kompatibility se staršími verzemi WSL.

Seznam souborů, které by měly a neměly být součástí konfigurace, najdete v doporučeních konfiguračních souborů .

Pokud chcete získat soubor tar existující linuxové distribuce, vyhledejte pokyny k exportu kontejneru Dockeru v Import jakékoli linuxové distribuce, která se má použít s WSL.

Jakmile bude archiv souborů tar připravený, podívejte se na Místní testování distribuce a vyzkoušejte ji místně.

Vytvoření přípony souboru .wsl

Posledním krokem, jakmile vytvoříte soubor tar představující vaši vlastní linuxovou distribuci, je změnit příponu souboru .tar na .wsl příponu souboru tím, že ji přejmenujete. Přejmenování této přípony souboru ji označí jako distribuci WSL. Jakmile se tar přejmenuje z .tar na .wsl, soubor se při otevření (dvojím kliknutím) správně nainstaluje ve Windows v Průzkumníku souborů. V souboru oobe.defaultName je vyžadována položka /etc/wsl-distribution.conf pro správné fungování této funkce poklepáním.

Rozšiřte svou distribuci WSL

Uživatelé WSL můžou zobrazit dostupné distribuce spuštěním wsl --list --online a mohou je nainstalovat přímo pomocí wsl --install <distroName> (nahrazení <distroName> skutečným názvem distribuce Linuxu. Tento proces je řízen souborem distribučního manifestu. Tento soubor manifestu můžete přidat do distribuce Linuxu zákazníka, aby byl zahrnut do možností příkazů wsl --install.

Vlastní distribuční tar pro Linux, který jste vytvořili a přejmenovali s příponou souboru .wsl, můžete distribuovat podle vlastního uvážení. Po stažení ho uživatel může nainstalovat přímo z příkazového řádku wsl --install --from-file <fileLocation> (nahrazením <fileLocation> skutečným umístěním souboru). Případně můžete soubor .wsl pro vaši vlastní distribuci WSL otevřít poklikáním.

Podrobnosti manifestu distribuce

Manifest distribuce obsahuje metadata o distribucích, které jsou k dispozici pro instalaci prostřednictvím wsl --install <distribution>.

Distribuce Linuxu, které jsou založené na tar, jsou uvedeny pod ModernDistribution, s následujícím formátem:

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

Každá položka flavor obsahuje seznam instalovatelných distribucí. Distribuce je možné nainstalovat buď prostřednictvím názvu příchutě (v takovém případě je nainstalovaná výchozí položka), nebo názvu verze.

Podívejte se, jak wsl --install příkazy fungují s následujícím manifestem:

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

Ukázkové instalační příkazy:

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

Přidání vaší distribuce do `wsl --install` pro všechny uživatele WSL

Aby byla vaše distribuce zahrnuta do seznamu pro příkaz: wsl --list --onlineMusí distribuce splňovat kritéria členství uvedená v distribučním seznamu adresátů. Tím zajistíte, že všechna uvedená rozdělení splňují nezbytné standardy zabezpečení.

Pokud vaše distribuce splňuje kritéria a chcete ji přidat do --install seznamu, odešlete žádost o přijetí změn do úložiště WSL GitHub (https://github.com/microsoft/WSL), které aktualizuje souborDistributionInfo.json podrobnostmi vaší distribuce. Tuto pull request zkontroluje tým WSL.

Přidání distribuce do `wsl --install` pro podnikovou nebo obchodní skupinu

Distribuci můžete zpřístupnit také v wsl --install jenom vybrané skupině úpravou klíčů registru na vybraných zařízeních s Windows.

Manifest distribuce WSL lze přepsat vytvořením hodnot registru v HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss.

DistributionListUrl: Přepíše adresu URL distribučního manifestu.
DistributionListUrlAppend: Přidání distribucí z adresy URL manifestu do seznamu instalovatelných distribucí

Obě hodnoty registru jsou řetězce (REG_SZ) a očekává se, že budou ve formátu adresy URL.

Počínaje verzí WSL 2.4.4 se podporuje protokol file://, který usnadňuje místní testování. Očekávaný formát je: file:///C:/path/to/file.

Místní testování distribuce

Abyste otestovali distribuční balíček tar, můžete použít následující ukázkový skript PowerShell pro přepsání manifestu distribuce novou distribucí. Nejprve uložte následující skript 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

Potom nakonfigurujte místní manifest spuštěním následujícího příkazu v PowerShellu se zvýšenými oprávněními:

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

Po dokončení by se měl zobrazit následující výstup 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

Potom můžete spustit wsl.exe --install test-distro-v1 a zkusit instalaci nové distribuce.

Až budete hotovi, můžete odstranit HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl a vrátit se k oficiálnímu manifestu.

Doporučení vlastní distribuce WSL pro Linux

Doporučení konfiguračních souborů

Ujistěte se, že vaše vlastní distribuce zahrnuje konfigurační soubory /etc/wsl.conf i /etc/wsl-distribution.conf. Oba soubory by měly vlastnit root:root a jejich oprávnění by měla být 0644.
Pokud se k vytvoření nového uživatele používá nastavení oobe.command, měly by být uid i oobe.defaultUid nastaveny na 1000.
Ujistěte se, že jste v konfiguračním souboru distribuce nastavili oobe.defaultName i shortcut.icon: /etc/wsl-distribution.conf
Nezahrnujte soubor /etc/resolv.conf do kořenového systému souborů.
Do /etc/passwdzahrnout uživatele root . uid tohoto kořenového uživatele by měl být 0.
V /etc/shadowby neměly být žádné hashované hesla.
Archiv by neměl obsahovat jádro ani initramfs.

Doporučení pro systemd

Pokud je systém povolen, jednotky, které můžou způsobit problémy s WSL, by měly být zakázány nebo maskovány. Níže uvedené jednotky můžou způsobovat problémy v distribucích WSL (platí pro systémové i uživatelské jednotky):

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

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-10-04