Criar uma distribuição personalizada do Linux para WSL

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:

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 ao WSL versão 2.4.4 e superior.

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:

1. /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.
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 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]
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 do 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/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 ajustando 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 sistemadas, incluindo se o sistema é 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 as recomendações do Systemd se você optar por ativar 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

Depois que os arquivos de distribuição e configuração estiverem em vigor, o sistema de arquivos raiz poderá 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 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 as recomendações de arquivo de configuração de 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 existente do Linux, encontre diretrizes sobre como exportar um contêiner do Docker em Importar qualquer distribuição do Linux a ser usada com o WSL.

Depois que o arquivo de tar estiver pronto, consulte o tópico Testar a distribuição localmente 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 personalizada do Linux, é alterar a extensão de arquivo .tar para uma extensão de arquivo .wsl 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 entrada de oobe.defaultName é necessária no arquivo /etc/wsl-distribution.conf para que essa experiência de clique duplo funcione corretamente.

Distribuir sua distribuição do 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 <distroName> 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 personalizado do Linux que você criou e renomeou com uma extensão de arquivo .wsl pode ser distribuído como desejar. Depois de baixado, um usuário pode instalá-lo diretamente da linha de comando com wsl --install --from-file <fileLocation> (substituindo <fileLocation> 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 do Linux baseadas em tar sã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 flavor entrada contém uma lista de distribuições instaláveis. As distribuições podem ser instaladas por meio do nome do sabor (nesse caso, a entrada padrão está instalada) ou o nome da versão.

Veja como os comandos wsl --install 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

Adicionar sua distribuição a 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 sigam os padrões de segurança necessários.

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

Adicionando sua distribuição a wsl --install para sua empresa ou grupo de negócios

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 criando valores de registro em 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 da versão 2.4.4 do WSL, há suporte para o protocolo file:// para facilitar o teste local. O formato esperado é: file:///C:/path/to/file.

Testar a distribuição localmente

Para testar um tar de distribuição, você pode usar o seguinte exemplo de script do 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 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.

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

Recomendações de arquivo de configuração

• Verifique se a distribuição personalizada inclui os arquivos de configuração /etc/wsl.conf e /etc/wsl-distribution.conf. Ambos os arquivos devem pertencer a root:root e suas permissões devem ser 0644.
• Se a configuração de oobe.command for usada para criar um novo usuário, uid e oobe.defaultUid deverão ser definidos 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 arquivo /etc/resolv.conf no sistema de arquivos raiz.
• Inclua um usuário raiz em /etc/passwd. O uid desse usuário raiz deve ser 0.
• Não deve haver hashes de senha. /etc/shadow
• O arquivo não deve conter um kernel ou um initramfs.

Recomendações sistemadas

Se o systemd estiver habilitado, as unidades que podem causar problemas com o WSL deverão ser desabilitadas ou mascaradas. As unidades abaixo são conhecidas por causar problemas em distribuições WSL (aplica-se a 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.mount