Criar uma distribuição personalizada do Linux para WSL

Artigo
11/19/2024

Este guia percorrerá as etapas para criar e distribuir uma distribuição WSL, que é um .wsl arquivo.

As distribuições WSL têm duas partes:

Um sistema de arquivos raiz (distribuído como um arquivo tar)
Uma entrada de manifesto (que contém os metadados de distribuição)

Observação

Este guia só se aplica ao WSL versão 2.4.4 e superior.

Observação

Consulte este repositório para obter as instruções anteriores de empacotamento de distribuição baseadas em appx.

O que são arquivos tar do sistema de arquivos raiz do WSL?

As distribuições WSL são definidas por um arquivo tar com uma .wsl extensão de arquivo no Windows.

Um arquivo TAR (abreviação de Tape Archive) é um tipo de arquivo usado para armazenar vários arquivos juntos em um único arquivo para facilitar a distribuição ou backup. O arquivo TAR contém o sistema de arquivos raiz de uma distribuição do Linux (todos os arquivos de distribuição), bem como os arquivos de configuração do WSL. Os arquivos de configuração do WSL informam ao sistema operacional Windows como instalar e iniciar a distribuição.

Depois de ter um sistema Linux que você gostaria de transformar em uma distribuição WSL, siga as etapas abaixo para começar.

Criar arquivos de configuração do WSL

Há dois arquivos de configuração que a distribuição deve incluir:

/etc/wsl-distribution.conf: Um arquivo criado pelo mantenedor da distribuição responsável por controlar como a distribuição do Linux deve ser configurada quando iniciada pela primeira vez com o WSL.
/etc/wsl.conf: Um arquivo que contém configurações globais do sistema que são específicas para o usuário e controlam como a distribuição é iniciada. Saiba mais sobre os arquivos de configuração do WSL.

Adicionar o arquivo de configuração de distribuição do WSL

O arquivo de configuração da distribuição, /etc/wsl-distribution.conf, define como a distribuição do Linux deve ser configurada quando iniciada pela primeira vez pelo usuário. Esse arquivo pode ser usado para criar interativamente uma conta de usuário, mostrar um contrato de licença, etc.

Aqui está um arquivo de amostra /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

Opções de configuração do arquivo de distribuição WSL:

chave	value	default	HDInsight
`oobe.command`	string	`<none>`	OOBE significa experiência pronta para uso. Esse comando é executado na primeira vez que o usuário abre um shell interativo na distribuição. Se esse comando retornar diferente de zero, ele será considerado malsucedido e o usuário não poderá abrir um shell.
`oobe.defaultUid`	Número inteiro	`<none>`	O UID padrão com o qual a distribuição começa. Isso é útil quando o `oobe.command` script cria um novo usuário.
`oobe.defaultName`	string	`<none>`	O nome padrão sob o qual a distribuição está registrada. Este nome padrão pode ser substituído pelo comando: `wsl.exe --install <distro> --name <name>`
`shortcut.icon`	string	O ícone padrão do WSL	O ícone no atalho do menu Iniciar para a distribuição. Deve estar em `.ico` formato com tamanho máximo de `10MB`
'windowsterminal.profileTemplate'	string	Caminho para um arquivo de modelo de terminal	O modelo JSON para gerar um perfil do Terminal do Windows para essa distribuição.

Você precisa criar uma experiência de primeira execução OOBE (experiência pronta para uso) para a distribuição. Abaixo está um exemplo de script bash que você pode usar. Este script pressupõe que oobe.defaultUid está definido como 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

Gerar um perfil do Terminal do Windows

O WSL gera automaticamente um perfil do Terminal do Windows quando uma distribuição é instalada. Os mantenedores de distribuição podem personalizar o perfil gerado pela configuração windowsterminal.profileTemplate no arquivo de configuração do WSL, /etc/wsl-distribution.conf.

O arquivo json segue o formato json do perfil do terminal. Aqui está um exemplo de perfil:


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

Esse arquivo não precisa especificar o perfil nameou commandLine. Eles são adicionados automaticamente pelo WSL ao gerar o perfil do terminal.

Adicionar uma configuração WSL para configurações locais por distribuição

No contexto de um sistema de arquivos raiz de distribuição, recomendamos que você defina as configurações do systemd, incluindo se o systemd é iniciado por padrão, nas /etc/wsl.conf configurações locais por distribuição. Veja o exemplo abaixo.

# /etc/wsl.conf

[boot]
systemd=true|false

O autor da distribuição determina se o systemd está habilitado por padrão definindo o boot.systemd valor como true (enabled) ou false (not enabled).

Consulte a seção de práticas recomendadas se você optar por habilitar o systemd por padrão.

Consulte Configuração de configurações avançadas no WSL para todas as configurações com suporte no /etc/wsl.conf.

Criar o arquivo tar

Uma vez que os arquivos de distribuição e configuração estejam no lugar, o sistema de arquivos raiz pode ser capturado em tar.

Abaixo está a maneira recomendada de criar o alcatrão:

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

A raiz do tar deve ser a raiz do sistema de arquivos (não um diretório contendo o sistema de arquivos raiz).

O formato de compactação recomendado é gzip. Outros formatos de compactação correm o risco de interromper a compatibilidade com versões mais antigas do WSL.

Consulte a seção de práticas recomendadas para arquivos que devem ou não ser incluídos

Para obter um arquivo TAR de uma distribuição Linux existente, encontre diretrizes sobre como exportar um contêiner do docker em Importar qualquer distribuição do Linux para usar com o WSL.

Quando o arquivo tar estiver pronto, consulte Substituindo o manifesto de distribuição para experimentá-lo localmente.

Criar uma extensão de arquivo .wsl

A etapa final, depois de criar um arquivo TAR para representar sua distribuição Linux personalizada, é alterar a extensão do .tar arquivo para uma .wsl extensão de arquivo renomeando-a. Renomear essa extensão de arquivo a marcará como uma distribuição WSL. Depois que o TAR for renomeado de .tar para .wsl, o arquivo será instalado corretamente no Windows quando aberto (clicado duas vezes) no Explorador de Arquivos. Uma oobe.defaultName entrada é necessária no /etc/wsl-distribution.conf arquivo para que essa experiência de clique duplo funcione corretamente

Distribuir sua distribuição WSL

Os usuários do WSL podem exibir distribuições disponíveis executando wsl --list --online e podem instalá-las diretamente com wsl --install <distroName> (substituindo pelo nome real da distribuição do Linux. Esse processo é controlado por um arquivo de manifesto de distribuição. Você pode adicionar esse arquivo de manifesto à distribuição Linux do cliente para que ele seja incluído nas opções de wsl --install comando.

O TAR de distribuição Linux personalizado que você criou e renomeou com uma .wsl extensão de arquivo pode ser distribuído como você quiser. Uma vez baixado, um usuário pode instalá-lo diretamente da linha de comando com wsl --install --from-file <fileLocation> (substituindo pelo local real do arquivo). Como alternativa, o .wsl arquivo para sua distribuição WSL personalizada pode ser aberto clicando duas vezes nele.

Detalhes do manifesto de distribuição

O manifesto de distribuição contém metadados sobre as distribuições que estão disponíveis para instalação via wsl --install <distribution>.

As distribuições baseadas em TAR estão listadas em ModernDistribution, com o formato abaixo:

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

Cada flavor entrada contém uma lista de distribuições instaláveis. As distribuições podem ser instaladas por meio do nome do tipo (nesse caso, a entrada padrão é instalada) ou do nome da versão.

Veja como wsl --install os comandos funcionam com o manifesto abaixo:

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

Exemplos de comandos de instalação:

$ 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

Adicionando sua distro para `wsl --install` todos os usuários do WSL

Para disponibilizar sua distribuição do WSL para todos os usuários, abra uma solicitação de pull no repositório GitHub do WSL que modifica o arquivo DistributionInfo.json para incluir suas informações de distribuição.

Essa solicitação de pull será examinada pela equipe do WSL.

Adicionando sua distro para `wsl --install` sua empresa ou grupo

Você também pode disponibilizar wsl --install sua distribuição apenas para um grupo selecionado editando as chaves do Registro nas máquinas escolhidas.

O manifesto de distribuição do WSL pode ser substituído criando valores do Registro no HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss.

DistributionListUrl: Substitui a URL do manifesto de distribuição
DistributionListUrlAppend: Adicione distribuições dessa URL de manifesto à lista de distribuições instaláveis

Ambos os valores do Registro são cadeias de caracteres (REG_SZ) e espera-se que estejam no formato URL. A partir do WSL 2.4.4, o file:// protocolo tem suporte para facilitar o teste local. O formato esperado é: file:///C:/path/to/file

Testando uma distribuição local

Para testar um tar de distribuição, você pode usar o script do PowerShell de exemplo a seguir para substituir o manifesto de distribuição pela nova distribuição. Primeiro salve o script abaixo como 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

Em seguida, configure o manifesto local executando o seguinte comando em um PowerShell com privilégios elevados:

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

Depois de concluído, você deverá ver a seguinte saída de 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

Em seguida, você pode executar wsl.exe --install test-distro-v1 para tentar a instalação da nova distribuição.

Quando terminar, você pode excluir HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl para reverter para o manifesto oficial.

Práticas recomendadas

Arquivos de configuração

/etc/wsl.conf e /etc/wsl-distribution.conf deve ser incluído. Eles devem ser de propriedade e root:root suas permissões devem ser 0644
Se oobe.command for usado para criar um novo usuário, seu uid deve ser 1000, e deve oobe.defaultUid ser definido com esse valor.
oobe.defaultName e shortcut.icon deve ser especificado em /etc/wsl-distribution.conf
/etc/resolv.conf NÃO deve ser incluído no sistema de arquivos raiz
Deve haver um usuário root e /etc/passwd seu uid deve ser 0
Não deve haver hashes de senha em /etc/shadow
O arquivo não deve conter um kernel ou um initramfs

Systemd

Se o systemd estiver habilitado, as unidades que podem causar problemas com o WSL deverão ser desabilitadas ou mascaradas. As unidades abaixo que são conhecidas por causar problemas nas distribuições WSL (aplica-se às unidades do sistema e do usuário):

systemd-resolved.serviço
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

Compartilhar via

Criar uma distribuição personalizada do Linux para WSL

O que são arquivos tar do sistema de arquivos raiz do WSL?

Criar arquivos de configuração do WSL

Adicionar o arquivo de configuração de distribuição do WSL

Gerar um perfil do Terminal do Windows

Adicionar uma configuração WSL para configurações locais por distribuição

Criar o arquivo tar

Criar uma extensão de arquivo .wsl

Distribuir sua distribuição WSL

Detalhes do manifesto de distribuição

Adicionando sua distro para `wsl --install` todos os usuários do WSL

Adicionando sua distro para `wsl --install` sua empresa ou grupo

Testando uma distribuição local

Práticas recomendadas

Arquivos de configuração

Systemd

Recursos adicionais

Compartilhar via

Criar uma distribuição personalizada do Linux para WSL

O que são arquivos tar do sistema de arquivos raiz do WSL?

Criar arquivos de configuração do WSL

Adicionar o arquivo de configuração de distribuição do WSL

Gerar um perfil do Terminal do Windows

Adicionar uma configuração WSL para configurações locais por distribuição

Criar o arquivo tar

Criar uma extensão de arquivo .wsl

Distribuir sua distribuição WSL

Detalhes do manifesto de distribuição

Adicionando sua distro para wsl --install todos os usuários do WSL

Adicionando sua distro para wsl --install sua empresa ou grupo

Testando uma distribuição local

Práticas recomendadas

Arquivos de configuração

Systemd

Recursos adicionais

Adicionando sua distro para `wsl --install` todos os usuários do WSL

Adicionando sua distro para `wsl --install` sua empresa ou grupo