建置 WSL 的自定義 Linux 散發套件

本指南將逐步解說建立和散發 WSL 散發套件的步驟，也就是檔案 .wsl 。

WSL 散發套件有兩個部分：

1. 根檔案系統（以 tar 檔案的形式散發）
2. 指令清單專案（其中包含散發元資料）

什麼是 WSL 根文件系統 tar 檔案？

WSL 散發套件是由 Windows 上擴展名為的 tar 檔案 .wsl 所定義。

TAR 檔案（磁帶封存簡短）是一種封存盤案，用來將多個檔案儲存在單一檔案中，以方便散發或備份。 TAR 檔案包含 Linux 發行版的根文件系統（所有散發檔案），以及 WSL 組態檔。 WSL 組態檔會告知 WIndows 作業系統如何安裝和啟動散發套件。

一旦您有想要進入 WSL 發行版的 Linux 系統，請遵循下列步驟來開始使用。

建立 WSL 組態檔

散發套件應該包含兩個組態檔：

1. /etc/wsl-distribution.conf：由散發維護者所建立的檔案，負責控制第一次使用 WSL 啟動時應如何設定 Linux 散發套件。
2. /etc/wsl.conf：包含用戶專屬的全域系統設定，並控制發佈啟動方式的檔案。 深入瞭解 WSL 組態檔。。

新增 WSL 散發配置檔

散發配置檔 /etc/wsl-distribution.conf會定義使用者第一次啟動時應該如何設定 Linux 散發套件。 此檔案可用來以互動方式建立用戶帳戶、顯示許可協定等。

以下是範例 /etc/wsl-distribution.conf 檔案：

# /etc/wsl-distribution.conf

[oobe]
command = /etc/oobe.sh
defaultUid = 1000
defaultName = my-distro

[shortcut]
icon = /usr/lib/wsl/my-icon.ico

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

WSL 散發檔案組態選項：

您需要為散發建立現用體驗 （OOBE） 初次執行體驗。 以下是您可以使用的範例 Bash 腳本。 這個文稿假設 設定 oobe.defaultUid 為 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/bin/deluser "$username"
    fi
  fi
done

產生 Windows 終端機 配置檔

安裝散發套件時，WSL 會自動產生 Windows 終端機 配置檔。 散發維護人員可以在 WSL 組態檔 /etc/wsl-distribution.conf中設定 windowsterminal.profileTemplate ，來自定義產生的配置檔。

json 檔案會 遵循終端機配置檔 json 格式。 以下是範例設定檔：

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

此檔案不需要指定 設定檔 name或 commandLine。 產生終端機配置檔時，WSL 會自動新增這些配置檔。

針對每個散發套件的本機設定新增 WSL 組態

在散發根文件系統的內容中，建議您設定 systemd 設定，包括 systemd 預設是否在個別散發的本機設定中 /etc/wsl.conf 啟動。 請參閱以下範例。

# /etc/wsl.conf

[boot]
systemd=true|false

散發作者會藉由將值設定 boot.systemd 為 true （enabled） 或 false [未啟用] 來判斷是否默認啟用 systemd。

如果您選擇預設啟用 systemd，請參閱最佳做法一節。

如需 中所有支持的設定，請參閱 WSL 中的進階設定組態 /etc/wsl.conf。

建立 tar 檔案

一旦發佈和組態檔就緒，就可以在 tar 中擷取根文件系統。

以下是建立 tar 的建議方式：

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

tar 的根目錄應該是檔案系統的根目錄（不是包含根文件系統的目錄）。

建議的壓縮格式為 gzip。 其他壓縮格式會執行與舊版 WSL 版本中斷相容性的風險。

請參閱應包含或不應該包含之檔案的最佳做法一節

若要取得現有 Linux 發行版的 TAR 檔案，請在匯入要與 WSL 搭配使用的任何 Linux 發行版中，尋找如何導出 Docker 容器的指引。

一旦 tar 檔案封存準備就緒，請參閱 覆寫散發指令清單 以在本機試用。

建立 .wsl 擴展名

一旦您建立 TAR 檔案來代表自定義 Linux 發行版，最後一個步驟就是藉由重新命名，將 .tar 擴展名變更為 .wsl 擴展名。 重新命名此擴展名會將它標示為WSL散發套件。 一旦將 TAR 重新命名.tar為 .wsl，檔案就會在 檔案總管 中開啟時，正確安裝在 Windows 上。 檔案中/etc/wsl-distribution.conf需要一個專案oobe.defaultName，才能讓此按兩下體驗正常運作

散發 WSL 散發套件

WSL 使用者可以執行 wsl --list --online 來檢視可用的散發套件，並可直接 wsl --install <distroName> 安裝它們（以 Linux 發行版的實際名稱取代 。 此程式是由散發指令清單檔案所控制。 您可以將此指令清單檔案新增至客戶 Linux 發行版，使其包含在命令選項中 wsl --install 。

您可以透過擴展名來散發您所建立和重新命名的 .wsl 自定義 Linux 散發套件 TAR。 下載之後，使用者可以直接從命令行 wsl --install --from-file <fileLocation> 安裝它（將 取代為檔案的實際位置）。 或者， .wsl 您可以按兩下自訂 WSL 散發套件的檔案加以開啟。

散發指令清單詳細數據

散發 指令清單 包含可透過 wsl --install <distribution>安裝之散發套件的相關元數據。

TAR 型散發套件列在 底下 ModernDistribution，格式如下：

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

每個 flavor 專案都包含可安裝的發行版清單。 散發套件可以透過類別名稱安裝（在此情況下，已安裝預設專案），或版本名稱。

檢視命令如何使用 wsl --install 下列指令清單：

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

範例安裝命令：

$ 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

將散發版本新增至 wsl --install 所有 WSL 使用者

若要讓您的 WSL 散發版本可供所有使用者使用，請在 WSL GitHub 存放庫上開啟提取要求，修改DistributionInfo.json檔案以包含您的散發版本資訊。

WSL 小組將會檢閱此提取要求。

將散發版本新增至 wsl --install 企業或群組

您也可以藉由編輯所選機器上的登錄機碼，將散發版本只提供給 wsl --install 選取的群組。

在 中 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss建立登錄值，即可覆寫 WSL 散發指令清單。

• DistributionListUrl：覆寫散發指令清單 URL
• DistributionListUrlAppend：從該指令清單 URL 將散發套件新增至可安裝散發套件清單

這兩個登錄值都是字串（REG_SZ），而且必須是URL格式。 從 WSL 2.4.4 開始，支援通訊 file:// 協定，讓本機測試更容易。 預期的格式為： file:///C:/path/to/file

測試本機散發套件

若要測試散發 tar，您可以使用下列範例 powershell 腳本，以新的散發覆寫散發指令清單。 首先將下列文稿儲存為 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 

然後在提升權限的 powershell 中執行下列命令，以設定本機指令清單：

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

完成後，您應該會看到下列輸出： 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

然後，您可以執行 wsl.exe --install test-distro-v1 以嘗試安裝新的散發套件。

完成時，您可以刪除 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl 以還原為官方指令清單。

最佳作法

組態檔

• /etc/wsl.conf 應該包含與 /etc/wsl-distribution.conf 。 它們應該由 root:root 擁有，而且其許可權應該是 0644
• 如果使用 oobe.command 來建立新的使用者，其 uid 應該是 1000，而且應該 oobe.defaultUid 設定為該值。
• oobe.defaultName 和 shortcut.icon 應該在 中指定 /etc/wsl-distribution.conf
• /etc/resolv.conf 不應該包含在根文件系統中
• 中應該有根使用者 /etc/passwd ，且其 uid 應為 0
• 中不應該有密碼哈希 /etc/shadow
• 封存不應包含核心或 initramfs

Systemd

如果已啟用 systemd，應該停用或遮罩可能導致 WSL 問題的單位。 下列已知會導致 WSL 散發套件問題的單位（適用於系統和用戶單位）：

• 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