Прочитать на английском

Поделиться через


Создание настраиваемого дистрибутива Linux для WSL

В этом руководстве описаны действия по созданию и распространению дистрибутива WSL, который является файлом .wsl .

Дистрибутивы WSL имеют две части:

  1. Корневая файловая система (распределен в виде tar-файла)
  2. Запись манифеста (которая содержит метаданные распространения)

Примечание

Это руководство относится только к WSL версии 2.4.4 и выше.

Примечание

См . этот репозиторий для предыдущих инструкций по упаковке дистрибутива на основе appx.

Что такое WSL корневая файловая система tar-файлы?

Дистрибутивы WSL определяются tar-файлом с расширением .wsl файла в Windows.

TAR-файл (короткий для ленточного архива) — это тип архивного файла, используемого для хранения нескольких файлов в одном файле для упрощения распределения или резервного копирования. TAR-файл содержит корневую файловую систему дистрибутива Linux (все файлы дистрибутива), а также файлы конфигурации WSL. Файлы конфигурации WSL сообщают операционной системе WIndows, как установить и запустить дистрибутив.

После того как у вас есть система Linux, которую вы хотите внести в дистрибутив WSL, выполните приведенные ниже действия, чтобы приступить к работе.

Создание файлов конфигурации WSL

Существует два файла конфигурации, которые следует включить в дистрибутив:

  1. /etc/wsl-distribution.conf: файл, созданный управляющий дистрибутивом, отвечающий за управление настройкой дистрибутива Linux при первом запуске с помощью WSL.
  2. /etc/wsl.conf: файл, содержащий глобальные параметры системы, относящиеся к пользователю, и управляет запуском дистрибутива. Дополнительные сведения о файлах конфигурации WSL..

Добавление файла конфигурации распространения WSL

Файл /etc/wsl-distribution.confконфигурации дистрибутива определяет, как следует настроить дистрибутив Linux при первом запуске пользователя. Этот файл можно использовать для интерактивного создания учетной записи пользователя, отображения лицензионного соглашения и т. д.

Ниже приведен пример /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

Параметры конфигурации файла распространения WSL:

key значение default примечаниями
oobe.command строка <none> OOBE выделяется вне коробки опыта. Эта команда запускается при первом открытии интерактивной оболочки в дистрибутиве. Если эта команда возвращает ненулевое значение, он считается неудачным, и пользователь не сможет открыть оболочку.
oobe.defaultUid integer <none> Пользовательский интерфейс по умолчанию, с которым начинается распределение. Это полезно при oobe.command создании скрипта нового пользователя.
oobe.defaultName строка <none> Имя по умолчанию, в которое зарегистрировано распределение. Это имя по умолчанию можно заменить командой: wsl.exe --install <distro> --name <name>
shortcut.icon строка Значок WSL по умолчанию Значок в контекстном меню "Пуск" для распространения. Должен быть в .ico формате с максимальным размером 10MB
'windowsterminal.profileTemplate' строка Путь к файлу шаблона терминала Шаблон JSON для создания профиля Терминал Windows для этого распределения.

Сначала необходимо создать интерфейс простого запуска (OOBE) для распространения. Ниже приведен пример скрипта bash, который можно использовать. В этом скрипте предполагается, что oobe.defaultUid задано значение 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

Создание профиля Терминал Windows

WSL автоматически создает профиль Терминал Windows при установке дистрибутива. В файле конфигурации WSL можно настроить созданный профиль, /etc/wsl-distribution.confсозданный в windowsterminal.profileTemplate файле конфигурации WSL.

Json-файл следует формату json профиля терминала. Ниже приведен пример профиля:


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

Этот файл не должен указывать профиль nameили commandLine. Они автоматически добавляются WSL при создании профиля терминала.

Добавление конфигурации WSL для локальных параметров на основе распределения

В контексте корневая файловая система распространения рекомендуется настроить системные параметры, включая запуск системных по умолчанию в /etc/wsl.conf локальных параметрах на основе распределения. См. пример ниже.

# /etc/wsl.conf

[boot]
systemd=true|false

Автор дистрибутива определяет, включена ли система по умолчанию, задав boot.systemd значение true (включено) или false (не включено).

Ознакомьтесь с разделом рекомендаций, если вы решили включить систему по умолчанию.

Дополнительные параметры см. в WSL для всех поддерживаемых /etc/wsl.confпараметров.

Создание tar-файла

После размещения файлов распространения и конфигурации корневая файловая система можно записать в tar.

Ниже приведен рекомендуемый способ создания тара:

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

Корневой каталог tar должен быть корнем файловой системы (а не каталогом, содержащим корневая файловая система).

Рекомендуемый формат сжатия — gzip. Другие форматы сжатия выполняют риск критической совместимости со старыми версиями WSL.

Ознакомьтесь с разделом рекомендаций по файлам, которые должны быть включены или не должны быть включены

Чтобы получить TAR-файл существующего дистрибутива Linux, найдите рекомендации по экспорту контейнера Docker в импорте любого дистрибутива Linux для использования с WSL.

После готовности архива tar-файла см . переопределение манифеста распространения для локального использования.

Создание расширения WSL-файла

После создания TAR-файла для представления пользовательского дистрибутива Linux необходимо изменить .tar расширение файла на .wsl расширение файла, переименовав его. Переименование этого расширения файла помечает его как дистрибутив WSL. После переименования .tar .wslTAR в файл будет правильно установлен в Windows при открытии (дважды щелкните) в проводник. Запись oobe.defaultName требуется в /etc/wsl-distribution.conf файле для правильной работы с этим интерфейсом двойного щелчка.

Распространение дистрибутива WSL

Пользователи WSL могут просматривать доступные дистрибутивы, запуская wsl --list --online их и напрямую устанавливая их (заменяя фактическим wsl --install <distroName> именем дистрибутива Linux. Этот процесс управляется файлом манифеста распространения. Этот файл манифеста можно добавить в дистрибутив Linux клиента, чтобы он был включен в wsl --install параметры команды.

Пользовательский дистрибутив Linux TAR, который вы создали и переименовали с расширением .wsl файла, можно распространить, однако, пожалуйста. После скачивания пользователь может установить его непосредственно из командной строки wsl --install --from-file <fileLocation> (заменив фактическое расположение файла). Кроме того, .wsl файл для настраиваемого дистрибутива WSL можно открыть, дважды щелкнув его.

Сведения о манифесте распространения

Манифест распространения содержит метаданные о дистрибутивах, доступных для установки с помощью wsl --install <distribution>.

Дистрибутивы на основе TAR перечислены в ModernDistributionследующем формате:

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

Каждая flavor запись содержит список устанавливаемых дистрибутивов. Дистрибутивы можно установить с помощью имени вкуса (в этом случае устанавливается запись по умолчанию) или имя версии.

Узнайте, как wsl --install команды работают с приведенным ниже манифестом:

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

Примеры команд установки:

$ 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

Добавление дистрибутива wsl --install для всех пользователей WSL

Чтобы сделать дистрибутив WSL доступным для всех пользователей, откройте запрос на вытягивание в репозитории WSL GitHub, который изменяет файл DistributionInfo.json для включения сведений о дистрибутиве.

Этот запрос на вытягивание будет проверен командой WSL.

Добавление дистрибутива wsl --install в ваше предприятие или группу

Вы также можете сделать дистрибутив доступным только для wsl --install группы выбора, изменив разделы реестра на выбранных компьютерах.

Манифест распространения WSL можно переопределить, создав значения реестра в HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss.

  • DistributionListUrl: переопределяет URL-адрес манифеста распространения
  • DistributionListUrlAppend: добавление дистрибутивов из этого URL-адреса манифеста в список устанавливаемых дистрибутивов

Оба значения реестра являются строками (REG_SZ) и, как ожидается, будут иметь формат URL-адреса. Начиная с WSL 2.4.4, file:// протокол поддерживается для упрощения локального тестирования. Ожидаемый формат: file:///C:/path/to/file

Тестирование локального дистрибутива

Чтобы проверить тар распространения, можно использовать следующий пример скрипта PowerShell для переопределения манифеста распространения с новым дистрибутивом. Сначала сохраните приведенный ниже сценарий следующим образом 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 

Затем настройте локальный манифест, выполнив следующую команду в powershell с повышенными привилегиями:

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

После завершения вы увидите следующие выходные данные из 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

Затем можно выполнить попытку wsl.exe --install test-distro-v1 установки нового дистрибутива.

После завершения можно удалить HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl , чтобы вернуться к официальному манифесту.

Рекомендации

Файлы конфигурации

  • /etc/wsl.conf и /etc/wsl-distribution.conf должны быть включены. Они должны принадлежать root:root и их разрешения должны быть 0644
  • Если oobe.command используется для создания нового пользователя, его пользовательский интерфейс должен быть 1000задан и должен oobe.defaultUid быть задан в этом значении.
  • oobe.defaultName и shortcut.icon должен быть указан в /etc/wsl-distribution.conf
  • /etc/resolv.confне следует включать в корневая файловая система
  • Должен быть корневой пользователь и /etc/passwd его пользовательский интерфейс должен быть 0
  • В хэши паролей не должно быть /etc/shadow
  • Архив не должен содержать ядро или инициамфы

Systemd

Если система включена, единицы, которые могут вызвать проблемы с WSL, должны быть отключены или маскированы. Приведенные ниже единицы, которые, как известно, вызывают проблемы в дистрибутивах WSL (применяется как к системным, так и к пользовательским единицам):

  • 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