Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Questa guida illustra i passaggi per creare e distribuire una distribuzione WSL, ovvero un .wsl file.
Le distribuzioni WSL hanno due parti:
- Un filesystem radice (distribuito come archivio tar)
- 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:
-
/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. -
/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.confche i file di configurazione di/etc/wsl-distribution.conf. Entrambi i file devono essere di proprietà diroot:roote le relative autorizzazioni devono essere0644. - Se l'impostazione
oobe.commandviene usata per creare un nuovo utente, siauidcheoobe.defaultUiddevono essere impostate su1000. - Assicurarsi di impostare sia
oobe.defaultNamecheshortcut.iconnel file di configurazione della distribuzione:/etc/wsl-distribution.conf - Non includere il file
/etc/resolv.confnel file system radice. - Si prega di includere un utente radice in
/etc/passwd. Iluidper questo utente root deve essere0. - 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
Collabora con noi su GitHub
L'origine di questo contenuto è disponibile in GitHub, in cui è anche possibile creare ed esaminare i problemi e le richieste pull. Per ulteriori informazioni, vedere la guida per i collaboratori.
Windows Subsystem for Linux