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 filesystem radice (distribuito come archivio tar)
  2. Voce del manifesto (che contiene i metadati di distribuzione)

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

Nota

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

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

Opzioni di configurazione del file di distribuzione WSL:

chiave valore predefinito note
oobe.command corda <none> OOBE sta per "out of box experience". 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 numero intero <none> UID predefinito con cui inizia la distribuzione. Ciò è utile quando lo oobe.command script crea un nuovo utente.
oobe.defaultName corda <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 corda Icona WSL predefinita L'icona nel collegamento del menu Start per la distribuzione. Deve essere in .ico formato con una dimensione massima di 10MB
shortcut.enabled booleano vero Indica se è necessario creare un collegamento al menu Start quando viene installata la distribuzione.
windowsterminal.profileTemplate corda <none> Modello JSON per generare un profilo di Terminale Windows per questa distribuzione.
windowsterminal.enabled booleano vero Indica se è necessario creare un profilo terminale quando viene installata la distribuzione. Se profileTemplate non è impostato, verrà generato un profilo predefinito.
windowsterminal.profileTemplate corda Percorso di un file modello di terminale Modello JSON per generare un profilo di Terminale Windows per questa distribuzione.

È necessario creare un'esperienza immediata e iniziale 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/sbin/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 systemd, incluso se systemd si avvia per impostazione predefinita, nelle impostazioni locali /etc/wsl.conf 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).

Se hai scelto di abilitare systemd per impostazione predefinita, vedere le raccomandazioni .

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 nel file tar.

Il modo consigliato per creare il file 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 principale).

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

Per un elenco dei file che devono e non devono essere inclusi nella configurazione, vedere i consigli del file di configurazione .

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 dei file tar è pronto, vedere Testare la distribuzione in locale per provarla in locale.

Creare un'estensione file .wsl

Il passaggio finale, dopo aver creato un file tar per rappresentare la distribuzione Linux personalizzata, consiste nel modificare l'estensione del file .tar in un'estensione di file .wsl 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. Per il corretto funzionamento di questa esperienza di doppio clic, è necessaria una voce oobe.defaultName nel file /etc/wsl-distribution.conf.

Distribuisci la tua versione WSL

Gli utenti WSL possono visualizzare le distribuzioni disponibili eseguendo wsl --list --online e possono installarle direttamente con wsl --install <distroName> (sostituendo <distroName> 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.

La distribuzione Linux personalizzata in formato tar che hai creato e rinominato con un'estensione di file .wsl può essere distribuita in qualsiasi modo tu preferisca. Dopo aver scaricato un utente può installarlo direttamente dalla riga di comando con wsl --install --from-file <fileLocation> (sostituendo <fileLocation> 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 linux 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 della variante (nel qual caso viene installata la voce predefinita) o il nome della versione.

Guarda come i comandi wsl --install funzionano con il seguente manifest:

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

Aggiungere la vostra 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 di WSL che modifica il file DistributionInfo.json per includere le informazioni di distribuzione.

Questa pull request verrà esaminata dal team WSL.

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

Puoi anche rendere disponibile la distribuzione in wsl --install solo a un gruppo selezionato modificando le chiavi del Registro di sistema nei dispositivi Windows 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: sostituisce l'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 versione 2.4.4, il protocollo file:// è supportato per semplificare i test locali. Il formato previsto è: file:///C:/path/to/file.

Testare la distribuzione in 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 powershell con privilegi elevati:

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

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

Raccomandazioni per la distribuzione di Linux personalizzate WSL

Consigli per i file di configurazione

  • Assicurarsi che la distribuzione personalizzata includa sia i file di configurazione /etc/wsl.conf che i file di configurazione di /etc/wsl-distribution.conf. Entrambi i file devono essere di proprietà di root:root e le relative autorizzazioni devono essere 0644.
  • Se l'impostazione oobe.command viene usata per creare un nuovo utente, sia uid che oobe.defaultUid devono essere impostate su 1000.
  • Assicurarsi di impostare sia oobe.defaultName che shortcut.icon nel file di configurazione della distribuzione: /etc/wsl-distribution.conf
  • Non includere il file /etc/resolv.conf nel file system radice.
  • Si prega di includere un utente radice in /etc/passwd. Il uid per questo utente root deve essere 0.
  • Non devono essere presenti hash delle password in /etc/shadow.
  • L'archivio non deve contenere un kernel o un initramfs.

Raccomandazioni di sistema

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

  • Servizio systemd-resolved
  • 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