Membangun Distribusi Linux Kustom untuk WSL

Panduan ini akan menelusuri langkah-langkah untuk membuat dan mendistribusikan distribusi WSL, yang merupakan .wsl file.

Distribusi WSL memiliki dua bagian:

  1. Sistem file akar (didistribusikan sebagai file tar)
  2. Entri daftar manifes (yang berisi metadata distribusi)

Panduan ini hanya berlaku untuk rilis WSL 2.4.4 dan yang lebih tinggi.

Catatan

Lihat repositori ini untuk instruksi pengemasan distribusi berbasis appx sebelumnya.

Apa itu file tar sistem file akar WSL?

Distribusi WSL didefinisikan oleh file tar dengan .wsl ekstensi file di Windows.

File TAR (singkatan dari Arsip Pita) adalah jenis file arsip yang digunakan untuk menyimpan beberapa file bersama-sama dalam satu file untuk distribusi atau pencadangan yang lebih mudah. File TAR berisi sistem file akar distribusi Linux (semua file distribusi), serta file konfigurasi WSL. File konfigurasi WSL memberi tahu sistem operasi WIndows cara menginstal dan meluncurkan distribusi.

Setelah Anda memiliki sistem Linux yang ingin Anda buat menjadi distribusi WSL, ikuti langkah-langkah di bawah ini untuk memulai.

Membuat file konfigurasi WSL

Ada dua file konfigurasi yang harus disertakan dalam distribusi:

  1. /etc/wsl-distribution.conf: File yang dibuat oleh penjaga distribusi yang bertanggung jawab untuk mengontrol bagaimana distribusi Linux harus dikonfigurasi saat pertama kali diluncurkan dengan WSL.
  2. /etc/wsl.conf: File yang berisi pengaturan sistem global yang khusus untuk pengguna dan mengontrol bagaimana distribusi diluncurkan. Pelajari selengkapnya tentang file konfigurasi WSL..

Menambahkan file konfigurasi distribusi WSL

File konfigurasi distribusi, /etc/wsl-distribution.conf, menentukan bagaimana distribusi Linux harus dikonfigurasi saat pertama kali diluncurkan oleh pengguna. File ini dapat digunakan untuk membuat akun pengguna secara interaktif, menunjukkan perjanjian lisensi, dll.

Berikut adalah file sampel /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

Opsi konfigurasi file distribusi WSL:

Kunci Nilai Bawaan Catatan
oobe.command string Tidak ada OOBE adalah singkatan dari pengalaman langsung setelah membuka kemasan. Perintah ini berjalan pertama kali pengguna membuka shell interaktif dalam distribusi. Jika perintah tersebut mengembalikan bukan nol, perintah tersebut dianggap tidak berhasil, dan pengguna tidak akan dapat membuka shell.
oobe.defaultUid bilangan bulat Tidak ada UID bawaan yang digunakan sebagai awal oleh distribusi. Ini berguna ketika skrip oobe.command membuat pengguna baru.
oobe.defaultName string Tidak ada Nama default tempat distribusi didaftarkan. Nama default ini dapat diganti dengan perintah : wsl.exe --install <distro> --name <name>
shortcut.icon string Ikon WSL bawaan Ikon pada pintasan menu Start untuk distribusi. Harus dalam format .ico dengan ukuran maksimum 10MB
shortcut.enabled Boolean benar Apakah pintasan menu Start harus dibuat saat distribusi diinstal.
windowsterminal.profileTemplate string Tidak ada Templat JSON untuk menghasilkan profil Terminal Windows untuk distribusi ini.
windowsterminal.enabled Boolean benar Apakah profil terminal harus dibuat saat distribusi diinstal. Jika profileTemplate tidak diatur, profil default akan dihasilkan.
windowsterminal.profileTemplate string Jalur ke file templat terminal Templat JSON untuk menghasilkan profil Terminal Windows untuk distribusi ini.

Anda perlu membuat pengalaman penggunaan pertama (OOBE) untuk distribusi. Di bawah ini adalah contoh skrip bash yang dapat Anda gunakan. Skrip ini mengasumsikan bahwa oobe.defaultUid diatur ke 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

Membuat profil Terminal Windows

WSL secara otomatis menghasilkan profil Terminal Windows saat distribusi diinstal. Pemelihara distribusi dapat menyesuaikan profil yang dihasilkan dengan mengatur windowsterminal.profileTemplate dalam file konfigurasi WSL, /etc/wsl-distribution.conf.

File JSON mengikuti format JSON profil terminal. Berikut adalah contoh 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"
    }
  ]
}

File ini tidak perlu menentukan profil name, atau commandLine. Mereka secara otomatis ditambahkan oleh WSL saat membuat profil terminal.

Tambahkan konfigurasi WSL untuk pengaturan lokal pada setiap distribusi

Dalam konteks sistem berkas root distribusi, kami menyarankan Anda mengonfigurasi pengaturan systemd, termasuk apakah systemd dimulai secara default, dalam /etc/wsl.conf pengaturan lokal sesuai dengan distribusi masing-masing. Lihat contoh di bawah ini.

# /etc/wsl.conf

[boot]
systemd=true|false

Penulis distribusi menentukan apakah systemd diaktifkan secara default dengan mengatur boot.systemd nilai ke true (diaktifkan) atau false (tidak diaktifkan).

Lihat rekomendasi Systemd jika Anda memilih untuk mengaktifkan systemd secara default.

Lihat Konfigurasi pengaturan tingkat lanjut di WSL untuk semua pengaturan yang didukung di /etc/wsl.conf.

Membuat file tar

Setelah file distribusi dan konfigurasi telah ditempatkan, sistem file akar dapat dikompres ke dalam file tar.

Cara yang direkomendasikan untuk membuat file tar:

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

Akar tar harus menjadi akar sistem file (bukan direktori yang berisi sistem file akar).

Format kompresi yang direkomendasikan adalah gzip. Format kompresi lainnya berisiko mengganggu kompatibilitas dengan versi WSL yang lebih lama.

Lihat rekomendasi file Konfigurasi untuk daftar file yang seharusnya dan tidak boleh disertakan dalam konfigurasi.

Untuk mendapatkan file tar dari distribusi Linux yang ada, temukan panduan tentang cara mengekspor kontainer docker di Mengimpor distribusi Linux apa pun untuk digunakan dengan WSL.

Setelah arsip file tar siap, lihat Uji distribusi secara lokal untuk mencobanya secara lokal.

Membuat ekstensi file .wsl

Langkah terakhir, setelah Anda membuat file tar untuk mewakili distribusi Linux kustom Anda, adalah mengubah ekstensi file .tar ke ekstensi file .wsl dengan mengganti nama. Mengganti nama ekstensi file ini akan menandainya sebagai distribusi WSL. Setelah tar diganti namanya dari .tar menjadi .wsl, file akan diinstal dengan benar di Windows ketika dibuka (diklik ganda) di File Explorer. Entri oobe.defaultName diperlukan dalam file /etc/wsl-distribution.conf agar pengalaman klik ganda ini berfungsi dengan baik.

Sebarkan distribusi WSL Anda

Pengguna WSL dapat melihat distribusi yang tersedia dengan menjalankan wsl --list --online dan dapat menginstalnya langsung dengan wsl --install <distroName> (mengganti <distroName> dengan nama aktual distribusi Linux. Proses ini dikendalikan oleh file manifes distribusi. Anda dapat menambahkan file manifes ini ke distribusi Linux pelanggan Anda agar disertakan dalam wsl --install opsi perintah.

Tar distribusi Linux kustom yang telah Anda buat dan ganti namanya dengan ekstensi file .wsl dapat didistribusikan sesuka Anda. Setelah diunduh, pengguna dapat menginstalnya langsung dari baris perintah dengan wsl --install --from-file <fileLocation> (mengganti <fileLocation> dengan lokasi file yang sebenarnya). Atau, .wsl file untuk distribusi WSL kustom Anda dapat dibuka dengan mengklik dua kali.

Rincian manifes distribusi

Manifest distribusi berisi metadata tentang distribusi yang dapat diinstal melalui .

Distribusi Linux yang berbasis tar tercantum di bawah ModernDistribution, dengan format di bawah ini:

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

Setiap flavor entri berisi daftar distribusi yang dapat diinstal. Distribusi dapat diinstal melalui nama varian (dalam hal ini, entri default akan diinstal) atau melalui nama versi.

Lihat bagaimana perintah wsl --install bekerja dengan manifes di bawah ini:

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

Contoh perintah penginstalan:

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

Menambah distribusi Anda ke wsl --install untuk semua pengguna WSL

Agar distribusi Anda disertakan dalam daftar untuk perintah: wsl --list --online, distribusi harus memenuhi kriteria Keanggotaan yang diuraikan dalam daftar surat distribusi. Ini memastikan bahwa semua distribusi yang tercantum mematuhi standar keamanan yang diperlukan.

Jika distribusi Anda memenuhi kriteria dan Anda ingin menambahkannya ke --install daftar, kirim permintaan pull pada repositori GitHub WSL (https://github.com/microsoft/WSL) yang memperbarui fileDistributionInfo.json dengan detail distribusi Anda. Permintaan pull ini akan ditinjau oleh tim WSL.

Menambahkan saluran distribusi Anda ke wsl --install untuk perusahaan atau grup bisnis Anda

Anda juga dapat membuat distribusi Anda tersedia di wsl --install hanya untuk grup tertentu dengan mengedit kunci registri pada perangkat Windows yang dipilih.

Manifes distribusi WSL dapat ditimpa dengan membuat nilai registri di HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss.

  • DistributionListUrl: Mengambil alih URL manifes distribusi
  • DistributionListUrlAppend: Tambahkan distribusi dari URL manifes tersebut ke daftar distribusi yang dapat diinstal

Kedua nilai registri adalah string (REG_SZ) dan diharapkan dalam format URL.

Dimulai dengan rilis WSL 2.4.4, protokol file:// didukung untuk membuat pengujian lokal lebih mudah. Format yang diharapkan adalah: file:///C:/path/to/file.

Menguji distribusi secara lokal

Untuk menguji distribusi tar, Anda dapat menggunakan contoh skrip Powershell berikut untuk mengganti manifes distribusi dengan distribusi baru. Pertama simpan skrip di bawah ini sebagai 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

Kemudian konfigurasikan manifes lokal dengan menjalankan perintah berikut di Powershell yang ditingkatkan:

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

Setelah selesai, Anda akan melihat output berikut dari 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

Anda kemudian dapat menjalankan wsl.exe --install test-distro-v1 untuk mencoba penginstalan distribusi baru.

Setelah selesai, Anda dapat menghapus HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl untuk kembali ke manifes resmi.

Rekomendasi distribusi Linux kustom WSL

Rekomendasi file konfigurasi

  • Pastikan distribusi kustom Anda menyertakan file konfigurasi /etc/wsl.conf dan /etc/wsl-distribution.conf. Kedua file harus dimiliki oleh root:root dan izinnya harus 0644.
  • Jika pengaturan oobe.command digunakan untuk membuat pengguna baru, uid dan oobe.defaultUid harus diatur ke 1000.
  • Pastikan Anda mengatur oobe.defaultName dan shortcut.icon dalam file konfigurasi distribusi: /etc/wsl-distribution.conf
  • Jangan sertakan /etc/resolv.conf file dalam sistem file akar.
  • Sertakan pengguna root di /etc/passwd. Nilai uid untuk pengguna root ini harus 0.
  • Seharusnya tidak ada hash kata sandi di /etc/shadow.
  • Arsip tidak boleh berisi kernel atau initramfs.

Rekomendasi systemd

Jika systemd diaktifkan, unit yang dapat menyebabkan masalah dengan WSL harus dinonaktifkan atau ditutupi. Unit di bawah ini diketahui menyebabkan masalah dalam distribusi WSL (berlaku untuk unit sistem dan pengguna):

  • 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
  • Last updated on