Crie uma distribuição Linux personalizada para WSL

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

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

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

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

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

As distribuições WSL são definidas por um arquivo tar com uma extensão de arquivo .wsl 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 Linux (todos os arquivos de distribuição), bem como os arquivos de configuração WSL. Os arquivos de configuração 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 WSL

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

1. /etc/wsl-distribution.conf: Um arquivo criado pelo mantenedor da distribuição responsável por controlar como a distribuição Linux deve ser configurada quando iniciada pela primeira vez com o WSL.
2. /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 WSL..

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

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

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

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

Você precisa criar uma experiência de primeira execução pronta para uso (OOBE) para a distribuição. Abaixo está um exemplo de script bash que você pode usar. Este script assume 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/sbin/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 configurando 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. Estes são adicionados automaticamente pela 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 ficheiros raiz de distribuição, recomendamos que configure as definições do systemd, incluindo se o systemd arranca por padrão, nas configurações locais /etc/wsl.conf, por distribuição. Veja o exemplo abaixo.

# /etc/wsl.conf

[boot]
systemd=true|false

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

Consulte as recomendações do Systemd se optou por ativar o systemd por defeito.

Consulte Configuração de definições avançadas no WSL para obter todas as definições suportadas no /etc/wsl.conf.

Criar o arquivo tar

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

A maneira recomendada de criar o arquivo tar:

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 que contém o sistema de arquivos raiz).

O formato de compressão recomendado é gzip. Outros formatos de compressão correm o risco de quebrar a compatibilidade com versões mais antigas da WSL.

Veja as recomendações do arquivo de configuração para obter uma lista de arquivos que devem e não devem ser incluídos na configuração.

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

Quando o arquivo tar estiver pronto, consulte Testar a distribuição localmente para experimentá-la 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 de arquivo .tar para uma extensão de arquivo .wsl, renomeando-a. Renomear esta extensão de arquivo irá marcá-lo como uma distribuição WSL. Uma vez que o tar tenha sido renomeado de .tar para .wsl, o arquivo será instalado corretamente no Windows quando aberto (clicado duas vezes) no Explorador de Arquivos. É necessária uma entrada oobe.defaultName no ficheiro /etc/wsl-distribution.conf para que esta experiência de duplo clique funcione corretamente.

Distribuir a sua distribuição WSL

Os usuários do WSL podem visualizar distribuições disponíveis executando wsl --list --online e podem instalá-las diretamente com wsl --install <distroName> (substituindo <distroName> pelo nome real da distribuição 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 comando wsl --install.

O tar de distribuição Linux personalizado que você criou e renomeou com uma extensão de arquivo .wsl pode ser distribuído como quiser. Uma vez baixado, um usuário pode instalá-lo diretamente da linha de comando com wsl --install --from-file <fileLocation> (substituindo <fileLocation> com a localização real do arquivo). Como alternativa, o arquivo .wsl 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 Linux 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 sha256 hash>"
                },
                "Arm64Url": {
                    "Url": "<tar url>",
                    "Sha256": "<tar sha256 hash>"
                }
            },
            {
                ...
            }
        ],
        "<flavor>": [
            ...
        ]
    }
}

Cada entrada flavor contém uma lista de distribuições instaláveis. As distribuições podem ser instaladas através do nome do sabor (caso em que a entrada padrão é instalada) ou do nome da versão.

Veja como wsl --install 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 distribuição ao wsl --install para todos os usuários do WSL

Para que sua distribuição seja incluída na lista do comando: wsl --list --online, a distribuição deve atender aos critérios de associação descritos na lista de endereçamento de distribuição. Isso garante que todas as distribuições listadas cumpram os padrões de segurança necessários.

Se sua distribuição atender aos critérios e você quiser adicioná-la à --install lista, envie uma solicitação pull no repositório GitHub da WSL (https://github.com/microsoft/WSL) que atualiza o arquivoDistributionInfo.json com os detalhes da sua distribuição. Este pull request será analisado pela equipa da WSL.

Adicionar a sua distribuição ao wsl --install para a sua empresa ou grupo empresarial

Você também pode disponibilizar sua distribuição em wsl --install apenas para um grupo selecionado, editando chaves do Registro nos dispositivos Windows escolhidos.

O manifesto de distribuição WSL pode ser substituído ao criar valores de registo em HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss.

• DistributionListUrl: Substitui o endereço do manifesto de distribuição
• DistributionListUrlAppend: Adicionar distribuições desse 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 da versão 2.4.4 do WSL, o protocolo file:// é suportado para facilitar os testes locais. O formato esperado é: file:///C:/path/to/file.

Testar a distribuição localmente

Para testar um tar de distribuição, podes usar o seguinte script de exemplo de PowerShell para substituir o manifesto de distribuição com a 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 elevado:

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

Uma vez concluído, você 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.

Recomendações de distribuição Linux personalizadas da WSL

Recomendações do arquivo de configuração

• Certifique-se de que sua distribuição personalizada inclua os arquivos de configuração /etc/wsl.conf e /etc/wsl-distribution.conf. Ambos os ficheiros devem ser de propriedade de root:root e as suas permissões devem ser 0644.
• Se a configuração oobe.command for usada para criar um novo usuário, tanto uid quanto oobe.defaultUid deverão ser definidas como 1000.
• Certifique-se de definir oobe.defaultName e shortcut.icon no arquivo de configuração de distribuição: /etc/wsl-distribution.conf
• Não inclua o ficheiro /etc/resolv.conf no sistema de ficheiros raiz.
• Inclua um usuário root no /etc/passwd. O uid para este usuário root deve ser 0.
• Não devem existir hashes de senha no /etc/shadow.
• O arquivo não deve conter um kernel ou um initramfs.

Recomendações do sistema:

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

• 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.montagem