Membangun Distribusi Linux Kustom untuk WSL

Artikel
11/19/2024

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

Distribusi WSL memiliki dua bagian:

Sistem file akar (didistribusikan sebagai file tar)
Entri manifes (yang berisi metadata distribusi)

Catatan

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:

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

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

Opsi konfigurasi file distribusi WSL:

kunci	value	Default	catatan
`oobe.command`	string	`<none>`	OOBE adalah singkatan dari pengalaman out of box. 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`	Integer	`<none>`	UID default yang dimulai dengan distribusi. Ini berguna ketika `oobe.command` skrip membuat pengguna baru.
`oobe.defaultName`	string	`<none>`	Nama default tempat distribusi didaftarkan. Nama default ini dapat diganti dengan perintah : `wsl.exe --install <distro> --name <name>`
`shortcut.icon`	string	Ikon WSL default	Ikon di pintasan menu mulai untuk distribusi. Harus dalam `.ico` format dengan ukuran maksimum `10MB`
'windowsterminal.profileTemplate'	string	Jalur ke file templat terminal	Templat JSON untuk menghasilkan profil Terminal Windows untuk distribusi ini.

Anda perlu membuat pengalaman out of box (OOBE) pengalaman eksekusi pertama 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/bin/deluser "$username"
    fi
  fi
done

Membuat profil Terminal Windows

WSL secara otomatis menghasilkan profil Terminal Windows saat distribusi diinstal. Pemeliharaan distribusi dapat menyesuaikan profil yang dihasilkan 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.

Menambahkan konfigurasi WSL untuk pengaturan lokal berdasarkan per distribusi

Dalam konteks sistem file akar distribusi, kami sarankan Anda mengonfigurasi pengaturan sistemd, termasuk apakah systemd dimulai secara default, dalam /etc/wsl.conf pengaturan lokal berdasarkan per distribusi. 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 bagian praktik terbaik 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 diberlakukan, sistem file akar dapat diambil dalam tar.

Di bawah ini adalah cara yang direkomendasikan untuk membuat 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 menjalankan risiko melanggar kompatibilitas dengan versi WSL yang lebih lama.

Lihat bagian praktik terbaik untuk file yang seharusnya, atau tidak boleh disertakan

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 Mengambil alih manifes distribusi untuk mencobanya secara lokal.

Membuat ekstensi file .wsl

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

Mendistribusikan distribusi WSL Anda

Pengguna WSL dapat melihat distribusi yang tersedia dengan menjalankan wsl --list --online dan dapat menginstalnya langsung dengan (mengganti dengan wsl --install <distroName> nama sebenarnya dari 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 .wsl ekstensi file dapat didistribusikan sesuka Anda. Setelah diunduh, pengguna dapat menginstalnya langsung dari baris perintah dengan wsl --install --from-file <fileLocation> (mengganti dengan lokasi file yang sebenarnya). Atau, .wsl file untuk distribusi WSL kustom Anda dapat dibuka dengan mengklik dua kali.

Detail manifes distribusi

Manifes distribusi berisi metadata tentang distribusi yang tersedia untuk penginstalan melalui wsl --install <distribution>.

Distribusi 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 sha265 hash>"
        },
    "Arm64Url": {
        "Url": "<tar url>",
        "Sha256": "<tar sha265 hash>"
        }
    }
}

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

Lihat cara wsl --install kerja perintah 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

Menambahkan distro Anda ke `wsl --install` untuk semua pengguna WSL

Untuk membuat distro WSL Anda tersedia untuk semua pengguna, buka permintaan pull pada repositori WSL GitHub yang memodifikasi file DistributionInfo.json untuk menyertakan informasi distro Anda.

Permintaan pull ini akan ditinjau oleh tim WSL.

Menambahkan distro Anda ke `wsl --install` untuk perusahaan atau grup Anda

Anda juga dapat membuat distro Anda hanya tersedia untuk wsl --install grup tertentu dengan mengedit kunci registri pada komputer 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 WSL 2.4.4, file:// protokol didukung untuk membuat pengujian lokal lebih mudah. Format yang diharapkan adalah: file:///C:/path/to/file

Menguji distribusi lokal

Untuk menguji tar distribusi, Anda dapat menggunakan contoh skrip powershell berikut untuk mengambil alih 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 dalam 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.

Praktik terbaik

File konfigurasi

/etc/wsl.conf dan /etc/wsl-distribution.conf harus disertakan. Mereka harus dimiliki oleh root:root dan izin mereka harus 0644
Jika oobe.command digunakan untuk membuat pengguna baru, uid-nya harus 1000, dan harus oobe.defaultUid diatur ke nilai tersebut.
oobe.defaultName dan shortcut.icon harus ditentukan dalam /etc/wsl-distribution.conf
/etc/resolv.conf TIDAK boleh disertakan dalam sistem file akar
Harus ada pengguna root di /etc/passwd dan uid-nya harus 0
Seharusnya tidak ada hash kata sandi di /etc/shadow
Arsip tidak boleh berisi kernel atau initramfs

Systemd

Jika systemd diaktifkan, unit yang dapat menyebabkan masalah dengan WSL harus dinonaktifkan atau ditutupi. Unit di bawah ini yang 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

Bagikan melalui

Membangun Distribusi Linux Kustom untuk WSL

Apa itu file tar sistem file akar WSL?

Membuat file konfigurasi WSL

Menambahkan file konfigurasi distribusi WSL

Membuat profil Terminal Windows

Menambahkan konfigurasi WSL untuk pengaturan lokal berdasarkan per distribusi

Membuat file tar

Membuat ekstensi file .wsl

Mendistribusikan distribusi WSL Anda

Detail manifes distribusi

Menambahkan distro Anda ke `wsl --install` untuk semua pengguna WSL

Menambahkan distro Anda ke `wsl --install` untuk perusahaan atau grup Anda

Menguji distribusi lokal

Praktik terbaik

File konfigurasi

Systemd

Sumber Daya Tambahan:

Bagikan melalui

Membangun Distribusi Linux Kustom untuk WSL

Apa itu file tar sistem file akar WSL?

Membuat file konfigurasi WSL

Menambahkan file konfigurasi distribusi WSL

Membuat profil Terminal Windows

Menambahkan konfigurasi WSL untuk pengaturan lokal berdasarkan per distribusi

Membuat file tar

Membuat ekstensi file .wsl

Mendistribusikan distribusi WSL Anda

Detail manifes distribusi

Menambahkan distro Anda ke wsl --install untuk semua pengguna WSL

Menambahkan distro Anda ke wsl --install untuk perusahaan atau grup Anda

Menguji distribusi lokal

Praktik terbaik

File konfigurasi

Systemd

Sumber Daya Tambahan:

Menambahkan distro Anda ke `wsl --install` untuk semua pengguna WSL

Menambahkan distro Anda ke `wsl --install` untuk perusahaan atau grup Anda