次の方法で共有


WSL 用のカスタム Linux ディストリビューションを構築する

このガイドでは、WSL ディストリビューション ( .wsl ファイル) を作成して配布する手順について説明します。

WSL ディストリビューションには、次の 2 つの部分があります。

  1. ルート ファイルシステム (tar ファイルとして配布)
  2. マニフェスト エントリ (ディストリビューション メタデータを含む)

このガイドは、 WSL リリース 2.4.4 以降にのみ適用されます。

appx ベースのディストリビューション パッケージの手順については このリポジトリを参照してください。

WSL ルート ファイルシステム tar ファイルとは何ですか?

WSL ディストリビューションは、Windows 上の .wsl ファイル拡張子を持つ tar ファイルによって定義されます。

TAR ファイル (テープ アーカイブの略) は、配布やバックアップを容易にするために複数のファイルを 1 つのファイルにまとめるために使用されるアーカイブ ファイルの一種です。 TAR ファイルには、Linux ディストリビューション (すべてのディストリビューション ファイル) のルート ファイル システムと WSL 構成ファイルが含まれています。 WSL 構成ファイルは、WIndows オペレーティング システムにディストリビューションをインストールして起動する方法を指示します。

WSL ディストリビューションにしたい Linux システムが完成したら、次の手順に従って作業を開始します。

WSL 構成ファイルを作成する

ディストリビューションに含める必要がある構成ファイルは 2 つあります。

  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]
enabled = true
icon = /usr/lib/wsl/my-icon.ico

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

WSL 配布ファイルの構成オプション:

価値 デフォルト
oobe.command ひも <none> OOBE は、すぐに使用するエクスペリエンスの略です。 このコマンドは、ユーザーがディストリビューションで対話型シェルを初めて開くと実行されます。 そのコマンドが 0 以外を返した場合、失敗したと見なされ、ユーザーはシェルを開くことができません。
oobe.defaultUid 整数 (integer) <none> ディストリビューションが開始する既定の UID。 これは、 oobe.command スクリプトで新しいユーザーを作成するときに便利です。
oobe.defaultName ひも <none> ディストリビューションが登録されている既定の名前。 この既定の名前は、次のコマンドに置き換えることができます。 wsl.exe --install <distro> --name <name>
shortcut.icon ひも 既定の WSL アイコン 配布のスタート メニュー ショートカットのアイコン。 最大サイズが a0/& .ico の形式である必要があります 10MB
shortcut.enabled ブーリアン ほんとう ディストリビューションのインストール時にスタート メニューのショートカットを作成するかどうかを指定します。
windowsterminal.profileTemplate ひも <none> このディストリビューションのWindows ターミナル プロファイルを生成する JSON テンプレート。
windowsterminal.enabled ブーリアン ほんとう ディストリビューションのインストール時にターミナル プロファイルを作成する必要があるかどうか。 profileTemplateが設定されていない場合は、既定のプロファイルが生成されます。
windowsterminal.profileTemplate ひも ターミナル テンプレート ファイルへのパス このディストリビューションのWindows ターミナル プロファイルを生成する JSON テンプレート。

ディストリビューションの最初の実行エクスペリエンス (OOBE) を作成する必要があります。 使用できる Bash スクリプトの例を次に示します。 このスクリプトでは、 oobe.defaultUid1000 に設定されていることを前提としています。

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

Windows ターミナル プロファイルを生成する

WSL では、ディストリビューションのインストール時にWindows ターミナル プロファイルが自動的に生成されます。 ディストリビューション メンテナーは、WSL 構成ファイル ( windowsterminal.profileTemplate) で/etc/wsl-distribution.confを設定することによって生成される生成されたプロファイルをカスタマイズできます。

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

このファイルでは、プロファイルの namecommandLineを指定する必要はありません。 これらは、端末プロファイルの生成時に WSL によって自動的に追加されます。

配布ごとにローカル設定の WSL 構成を追加する

ディストリビューション ルート ファイルシステムのコンテキストでは、配布ごとに/etc/wsl.confローカル設定で systemd が既定で開始されるかどうかなど、systemd 設定を構成することをお勧めします。 次の例を見てください。

# /etc/wsl.conf

[boot]
systemd=true|false

配布作成者は、 boot.systemd 値を true (有効) または false (有効ではない) に設定することで、systemd が既定で有効になっているかどうかを判断します。

既定で systemd を有効にすることを選択した場合は、Systemd の推奨事項を参照してください。

でサポートされているすべての設定については/etc/wsl.confAdvanced 設定の構成を参照してください。

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 ファイル拡張子を作成する

最後の手順では、カスタム Linux ディストリビューションを表す tar ファイルを作成したら、名前を変更して .tar ファイル拡張子を .wsl ファイル拡張子に変更します。 このファイル拡張子の名前を変更すると、WSL ディストリビューションとしてマークされます。 tar の名前を .tar から .wsl に変更すると、エクスプローラーで開くと (ダブルクリックして) Windows にファイルが正しくインストールされます。 このダブルクリック エクスペリエンスを正常に機能させるには、oobe.defaultName ファイルに/etc/wsl-distribution.confエントリが必要です。

WSL ディストリビューションを配布する

WSL ユーザーは、 wsl --list --online を実行して使用可能なディストリビューションを表示し、 wsl --install <distroName> で直接インストールできます ( <distroName> を Linux ディストリビューションの実際の名前に置き換えます)。 このプロセスは、配布マニフェスト ファイルによって制御されます。 このマニフェスト ファイルを顧客の Linux ディストリビューションに追加して、 wsl --install コマンド オプションに含めることができます。

.wslファイル拡張子を使用して作成および名前を変更したカスタム Linux ディストリビューション tar は、必要に応じて配布できます。 ダウンロードしたユーザーは、コマンド ラインから wsl --install --from-file <fileLocation> で直接インストールできます ( <fileLocation> をファイルの実際の場所に置き換えます)。 または、カスタム WSL ディストリビューションの .wsl ファイルをダブルクリックして開くことができます。

ディストリビューション マニフェストの詳細

配布マニフェストには、wsl --install <distribution>経由でインストールできるディストリビューションに関するメタデータが含まれています。

tar ベースの Linux ディストリビューションは、次の形式で 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 ユーザーの wsl --install にディストリビューションを追加する

WSL ディストリビューションをすべてのユーザーが使用できるようにするには、 WSL GitHub リポジトリ でプル要求を開き、配布情報を含むように DistributionInfo.json ファイルを変更します。

このプル要求は、WSL チームによってレビューされます。

企業またはビジネス グループの wsl --install にディストリビューションを追加する

また、選択した Windows デバイスのレジストリ キーを編集して、 wsl --install で選択したグループにのみ配布を使用できるようにすることもできます。

WSL 分散マニフェストは、 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxssでレジストリ値を作成することでオーバーライドできます。

  • 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 を削除して公式マニフェストに戻すことができます。

WSL カスタム Linux ディストリビューションの推奨事項

構成ファイルの推奨事項

  • カスタム配布に、 /etc/wsl.conf 構成ファイルと /etc/wsl-distribution.conf 構成ファイルの両方が含まれていることを確認します。 両方のファイルは root:root によって所有されている必要があり、それらのアクセス許可は 0644する必要があります。
  • oobe.command設定を使用して新しいユーザーを作成する場合は、uidoobe.defaultUidの両方を1000に設定する必要があります。
  • 配布構成ファイルで oobe.defaultNameshortcut.icon の両方を設定してください。 /etc/wsl-distribution.conf
  • ルート ファイルシステムにファイル /etc/resolv.conf を含めないでください。
  • /etc/passwdにルート ユーザーを含めます。 このルート ユーザーの uid0する必要があります。
  • /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