Leggere in inglese

Condividi tramite


Creare una distribuzione Linux personalizzata per WSL

Questa guida illustra i passaggi per creare e distribuire una distribuzione WSL, ovvero un .wsl file.

Le distribuzioni WSL hanno due parti:

  1. Un file system radice (distribuito come file tar)
  2. Voce del manifesto (che contiene i metadati di distribuzione)

Nota

Questa guida si applica solo a WSL versione 2.4.4 e successive.

Nota

Vedere questo repository per le istruzioni precedenti per la creazione di pacchetti di distribuzione basata su appx.

Che cosa sono i file tar del file system radice WSL?

Le distribuzioni WSL sono definite da un file tar con estensione .wsl di file in Windows.

Un file TAR (short for Tape Archive) è un tipo di file di archivio usato per archiviare più file in un unico file per facilitare la distribuzione o il backup. Il file TAR contiene il file system radice di una distribuzione Linux (tutti i file di distribuzione), nonché i file di configurazione WSL. I file di configurazione WSL indicano al sistema operativo WIndows come installare e avviare la distribuzione.

Dopo aver creato un sistema Linux che si vuole creare in una distribuzione WSL, seguire questa procedura per iniziare.

Creare file di configurazione WSL

Esistono due file di configurazione che la distribuzione deve includere:

  1. /etc/wsl-distribution.conf: file creato dal responsabile della gestione della distribuzione responsabile del controllo della configurazione della distribuzione Linux al primo avvio con WSL.
  2. /etc/wsl.conf: file contenente impostazioni di sistema globali specifiche per l'utente e controllare la modalità di avvio della distribuzione. Altre informazioni sui file di configurazione WSL.

Aggiungere il file di configurazione della distribuzione WSL

Il file di configurazione della distribuzione, /etc/wsl-distribution.conf, definisce la modalità di configurazione della distribuzione Linux al primo avvio da parte dell'utente. Questo file può essere usato per creare in modo interattivo un account utente, mostrare un contratto di licenza e così via.

Ecco un file di esempio /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

Opzioni di configurazione del file di distribuzione WSL:

key value default note
oobe.command string <none> Configurazione guidata si distingue per l'esperienza predefinita. Questo comando viene eseguito la prima volta che l'utente apre una shell interattiva nella distribuzione. Se il comando restituisce un valore diverso da zero, viene considerato non riuscito e l'utente non sarà in grado di aprire una shell.
oobe.defaultUid integer <none> UID predefinito con cui inizia la distribuzione. Ciò è utile quando lo oobe.command script crea un nuovo utente.
oobe.defaultName string <none> Nome predefinito in cui è registrata la distribuzione. Questo nome predefinito può essere sostituito con il comando : wsl.exe --install <distro> --name <name>
shortcut.icon string Icona WSL predefinita Icona nel collegamento del menu Start per la distribuzione. Deve essere in .ico formato con una dimensione massima di 10MB
'windowsterminal.profileTemplate' string Percorso di un file modello di terminale Modello JSON per generare un profilo di Terminale Windows per questa distribuzione.

È necessario creare un'esperienza guidata per la prima esecuzione per la distribuzione. Di seguito è riportato uno script bash di esempio che è possibile usare. Questo script presuppone che oobe.defaultUid sia impostato su 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

Generare un profilo di Terminale Windows

WSL genera automaticamente un profilo di Terminale Windows quando viene installata una distribuzione. I gestori di distribuzione possono personalizzare il profilo generato impostando windowsterminal.profileTemplate nel file di configurazione WSL . /etc/wsl-distribution.conf

Il file JSON segue il formato JSON del profilo del terminale. Ecco un profilo di esempio:


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

Questo file non deve specificare il profilo nameo commandLine. Questi vengono aggiunti automaticamente da WSL durante la generazione del profilo del terminale.

Aggiungere una configurazione WSL per le impostazioni locali in base alla distribuzione

Nel contesto di un file system radice di distribuzione, è consigliabile configurare le impostazioni di sistema, tra cui se systemd viene avviato per impostazione predefinita, nelle /etc/wsl.conf impostazioni locali in base alla distribuzione. Vedi l'esempio seguente.

# /etc/wsl.conf

[boot]
systemd=true|false

L'autore della distribuzione determina se systemd è abilitato per impostazione predefinita impostando il boot.systemd valore su true (abilitato) o false (non abilitato).

Vedere la sezione procedure consigliate se si sceglie di abilitare systemd per impostazione predefinita.

Vedere Configurazione delle impostazioni avanzate in WSL per tutte le impostazioni supportate in /etc/wsl.conf.

Creare il file tar

Dopo aver creato i file di distribuzione e configurazione, il file system radice può essere acquisito in tar.

Di seguito è riportato il modo consigliato per creare il tar:

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

La radice del file tar deve essere la radice del file system (non una directory contenente il file system radice).

Il formato di compressione consigliato è gzip. Altri formati di compressione comportano il rischio di interruzione della compatibilità con le versioni precedenti di WSL.

Vedere la sezione procedure consigliate per i file che devono essere inclusi o che non devono essere inclusi

Per ottenere un file TAR di una distribuzione Linux esistente, vedere indicazioni su come esportare un contenitore Docker in Importare qualsiasi distribuzione Linux da usare con WSL.

Quando l'archivio file tar è pronto, vedere Override del manifesto di distribuzione per provarlo in locale.

Creare un'estensione di file con estensione wsl

Il passaggio finale, dopo aver creato un file TAR per rappresentare la distribuzione Linux personalizzata, consiste nel modificare l'estensione di file in un'estensione .tar .wsl di file rinominandola. La ridenominazione di questa estensione di file lo contrassegnerà come distribuzione WSL. Dopo aver rinominato TAR da .tar a .wsl, il file verrà installato correttamente in Windows quando si apre (facendo doppio clic) in Esplora file. Nel file è necessaria /etc/wsl-distribution.conf una oobe.defaultName voce per il corretto funzionamento di questa esperienza di doppio clic

Distribuire la distribuzione WSL

Gli utenti WSL possono visualizzare le distribuzioni disponibili eseguendo wsl --list --online e possono installarle direttamente con wsl --install <distroName> (sostituendo con il nome effettivo della distribuzione Linux. Questo processo è controllato da un file manifesto di distribuzione. È possibile aggiungere questo file manifesto alla distribuzione Linux del cliente affinché sia incluso nelle opzioni di wsl --install comando.

Il tar di distribuzione Linux personalizzato creato e rinominato con un'estensione .wsl di file può tuttavia essere distribuito. Dopo aver scaricato un utente può installarlo direttamente dalla riga di comando con wsl --install --from-file <fileLocation> (sostituendo con il percorso effettivo del file). In alternativa, è possibile aprire il .wsl file per la distribuzione WSL personalizzata facendo doppio clic su di esso.

Dettagli del manifesto di distribuzione

Il manifesto di distribuzione contiene i metadati relativi alle distribuzioni disponibili per l'installazione tramite wsl --install <distribution>.

Le distribuzioni basate su TAR sono elencate in ModernDistribution, con il formato seguente:

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

Ogni flavor voce contiene un elenco di distribuzioni installabili. Le distribuzioni possono essere installate tramite il nome del gusto (nel qual caso la voce predefinita è installata) o il nome della versione.

Vedere come wsl --install funzionano i comandi con il manifesto seguente:

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

Comandi di installazione di esempio:

$ 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

Aggiunta della distribuzione a wsl --install per tutti gli utenti WSL

Per rendere disponibile la distribuzione WSL a tutti gli utenti, aprire una richiesta pull nel repository GitHub WSL che modifica il file DistributionInfo.json per includere le informazioni sulla distribuzione.

Questa richiesta pull verrà esaminata dal team WSL.

Aggiunta della distribuzione a wsl --install per l'azienda o il gruppo

È anche possibile rendere disponibile la distribuzione solo in wsl --install un gruppo selezionato modificando le chiavi del Registro di sistema nei computer scelti.

È possibile eseguire l'override del manifesto di distribuzione WSL creando valori del Registro di sistema in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss.

  • DistributionListUrl: esegue l'override dell'URL del manifesto di distribuzione
  • DistributionListUrlAppend: aggiungere distribuzioni dall'URL del manifesto all'elenco delle distribuzioni installabili

Entrambi i valori del Registro di sistema sono stringhe (REG_SZ) e devono essere in formato URL. A partire da WSL 2.4.4, il protocollo è supportato per semplificare i file:// test locali. Il formato previsto è: file:///C:/path/to/file

Test di una distribuzione locale

Per testare un tar di distribuzione, è possibile usare lo script di PowerShell di esempio seguente per eseguire l'override del manifesto di distribuzione con la nuova distribuzione. Salvare prima di tutto lo script seguente come 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 

Configurare quindi il manifesto locale eseguendo il comando seguente in una powershell con privilegi elevati:

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

Al termine, verrà visualizzato l'output seguente da 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

È quindi possibile eseguire wsl.exe --install test-distro-v1 per provare l'installazione della nuova distribuzione.

Al termine, è possibile eliminare HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl per ripristinare il manifesto ufficiale.

Procedure consigliate

File di configurazione

  • /etc/wsl.conf e /etc/wsl-distribution.conf devono essere inclusi. Devono essere di proprietà di root:root e le relative autorizzazioni devono essere 0644
  • Se oobe.command viene usato per creare un nuovo utente, l'uid deve essere 1000e deve oobe.defaultUid essere impostato su tale valore.
  • oobe.defaultName e shortcut.icon deve essere specificato in /etc/wsl-distribution.conf
  • /etc/resolv.conf NON deve essere incluso nel file system radice
  • Dovrebbe essere presente un utente radice in /etc/passwd e l'interfaccia utente deve essere 0
  • Non devono essere presenti hash delle password in /etc/shadow
  • L'archivio non deve contenere un kernel o un initramfs

Systemd

Se systemd è abilitato, le unità che possono causare problemi con WSL devono essere disabilitate o mascherate. Le unità seguenti note per causare problemi nelle distribuzioni WSL (si applicano sia alle unità di sistema che alle unità utente):

  • 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