このガイドでは、WSL ディストリビューション ( .wsl
ファイル) を作成して配布する手順について説明します。
WSL ディストリビューションには、次の 2 つの部分があります。
- ルート ファイルシステム (tar ファイルとして配布)
- マニフェスト エントリ (ディストリビューション メタデータを含む)
このガイドは、 WSL リリース 2.4.4 以降にのみ適用されます。
注
前 appx ベースのディストリビューション パッケージの手順については このリポジトリを参照してください。
WSL ルート ファイルシステム tar ファイルとは何ですか?
WSL ディストリビューションは、Windows 上の .wsl
ファイル拡張子を持つ tar ファイルによって定義されます。
TAR ファイル (テープ アーカイブの略) は、配布やバックアップを容易にするために複数のファイルを 1 つのファイルにまとめるために使用されるアーカイブ ファイルの一種です。 TAR ファイルには、Linux ディストリビューション (すべてのディストリビューション ファイル) のルート ファイル システムと WSL 構成ファイルが含まれています。 WSL 構成ファイルは、WIndows オペレーティング システムにディストリビューションをインストールして起動する方法を指示します。
WSL ディストリビューションにしたい Linux システムが完成したら、次の手順に従って作業を開始します。
WSL 構成ファイルを作成する
ディストリビューションに含める必要がある構成ファイルは 2 つあります。
-
/etc/wsl-distribution.conf
: WSL を使用して初めて起動したときに Linux ディストリビューションを構成する方法を制御するディストリビューション 保守管理者によって作成されたファイル。 -
/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.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/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"
}
]
}
このファイルでは、プロファイルの name
や commandLine
を指定する必要はありません。 これらは、端末プロファイルの生成時に WSL によって自動的に追加されます。
配布ごとにローカル設定の WSL 構成を追加する
ディストリビューション ルート ファイルシステムのコンテキストでは、配布ごとに/etc/wsl.conf
ローカル設定で systemd が既定で開始されるかどうかなど、systemd 設定を構成することをお勧めします。 次の例を見てください。
# /etc/wsl.conf
[boot]
systemd=true|false
配布作成者は、 boot.systemd
値を true
(有効) または false
(有効ではない) に設定することで、systemd が既定で有効になっているかどうかを判断します。
既定で systemd を有効にすることを選択した場合は、Systemd の推奨事項を参照してください。
でサポートされているすべての設定については/etc/wsl.conf
Advanced 設定の構成を参照してください。
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
設定を使用して新しいユーザーを作成する場合は、uid
とoobe.defaultUid
の両方を1000
に設定する必要があります。 - 配布構成ファイルで
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
Windows Subsystem for Linux