WSL용 사용자 지정 Linux 배포 빌드

이 가이드에서는 .wsl 파일인 WSL 배포판을 생성하고 배포하는 단계를 안내합니다.

WSL 배포에는 두 부분으로 구성됩니다.

1. 루트 파일 시스템(tar 파일로 배포)
2. 매니페스트 항목(배포 메타데이터 포함)

이 가이드는 WSL 릴리스 2.4.4 이상에만 적용됩니다.

참고

이전 appx 기반 배포 패키징 지침은 이 리포지토리를 참조하세요.

WSL 루트 파일 시스템 tar 파일은 무엇인가요?

WSL 배포판은 Windows에서 .wsl 파일 확장자를 가진 tar 파일로 정의됩니다.

TAR 파일(테이프 보관의 약식)은 배포 또는 백업을 용이하게 하기 위해 여러 파일을 단일 파일에 함께 저장하는 데 사용되는 보관 파일 형식입니다. TAR 파일에는 WSL 구성 파일뿐만 아니라 Linux 배포의 루트 파일 시스템(모든 배포 파일)이 포함됩니다. WSL 구성 파일은 WIndows 운영 체제에 배포를 설치하고 시작하는 방법을 알려줍니다.

WSL 배포에 적용하려는 Linux 시스템이 있으면 아래 단계에 따라 시작합니다.

WSL 구성 파일 만들기

배포에 포함해야 하는 두 가지 구성 파일이 있습니다.

1. /etc/wsl-distribution.conf: WSL을 사용하여 처음 시작할 때 Linux 배포를 구성하는 방법을 제어하는 배포 유지 관리자가 만든 파일입니다.
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]
enabled = true
icon = /usr/lib/wsl/my-icon.ico

[windowsterminal]
enabled = true
ProfileTemplate = /usr/lib/wsl/terminal-profile.json

WSL 배포 파일 구성 옵션:

열쇠	가치	디폴트	메모
oobe.command	문자열	<none>	OOBE는 제품 개봉 후 첫 경험을 의미합니다. 이 명령은 사용자가 배포에서 대화형 셸을 처음 열 때 실행됩니다. 이 명령이 0이 아닌 경우 실패한 것으로 간주되며 사용자가 셸을 열 수 없습니다.
oobe.defaultUid	정수	<none>	배포가 시작되는 기본 UID입니다. 이 기능은 스크립트에서 oobe.command 새 사용자를 만들 때 유용합니다.
oobe.defaultName	문자열	<none>	배포판이 등록된 기본 이름입니다. 이 기본 이름은 다음 명령으로 바꿀 수 있습니다. wsl.exe --install <distro> --name <name>
shortcut.icon	문자열	기본 WSL 아이콘	배포에 대한 시작 메뉴 바로 가기의 아이콘입니다. 최대 크기가 .ico인 10MB 형식이어야 합니다.
shortcut.enabled	부울	진실	배포가 설치될 때 시작 메뉴 바로 가기를 만들어야 하는지 여부입니다.
windowsterminal.profileTemplate	문자열	<none>	이 배포에 대한 Windows 터미널 프로필을 생성하는 JSON 템플릿입니다.
windowsterminal.enabled	부울	진실	배포가 설치될 때 터미널 프로필을 만들어야 하는지 여부입니다. profileTemplate 설정되지 않으면 기본 프로필이 생성됩니다.
windowsterminal.profileTemplate	문자열	터미널 템플릿 파일의 경로	이 배포에 대한 Windows 터미널 프로필을 생성하는 JSON 템플릿입니다.

배포에 대한 첫 번째 실행 환경(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/sbin/deluser "$username"
    fi
  fi
done

Windows 터미널 프로필 생성

WSL은 배포가 설치될 때 Windows 터미널 프로필을 자동으로 생성합니다. 배포 유지 관리자는 WSL 구성 파일 windowsterminal.profileTemplate에서 설정 /etc/wsl-distribution.conf 하여 생성된 프로필을 사용자 지정할 수 있습니다.

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 로컬 설정에서 systemd가 기본적으로 시작되는지 여부를 포함한 systemd 설정을 구성할 것을 권장합니다. 아래 예제를 참조하세요.

# /etc/wsl.conf

[boot]
systemd=true|false

배포 작성자는 기본적으로 systemd가 활성화되는지 여부를 결정하기 위해 값을 boot.systemd로 설정하여 true (사용) 또는 false (사용 안 함) 중 하나를 선택합니다.

기본적으로 systemd를 사용하도록 선택한 경우 Systemd 권장 사항을 참조하세요.

에서 지원되는 모든 설정은 WSL의 고급 설정 구성을 참조하세요./etc/wsl.conf

tar 파일 만들기

배포 및 구성 파일이 배치되면 루트 파일 시스템을 tar 파일에서 캡처할 수 있습니다.

tar 파일을 만드는 권장 방법은 다음과 같습니다.

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

tar의 루트는 파일 시스템의 루트여야 합니다(루트 파일 시스템 포함하는 디렉터리가 아님).

권장되는 압축 형식은 gzip입니다. 다른 압축 형식은 이전 WSL 버전과의 호환성이 손상될 위험이 있습니다.

구성에 포함해야 하고 포함해서는 안 되는 파일 목록은 구성 파일 권장 사항을 참조하세요.

기존 Linux 배포의 tar 파일을 가져오려면 WSL 사용할 Linux 배포판 가져오기를Docker 컨테이너를 내보내는 방법에 대한 지침을 찾습니다.

tar 파일 보관이 준비되면 로컬에서 배포를 테스트하기 위해을 참조 하세요.

.wsl 파일 확장명 만들기

사용자 지정 Linux 배포를 나타내는 tar 파일을 만든 후 마지막 단계는 이름을 변경하여 .tar 파일 확장자를 .wsl 파일 확장명으로 변경하는 것입니다. 이 파일 확장명 이름을 바꾸면 WSL 배포로 표시됩니다. tar 이름이 .tar.wsl변경되면 파일 탐색기에서 열면 파일이 Windows에 올바르게 설치됩니다(두 번 클릭). 이 두 번 클릭 환경이 제대로 작동하려면 oobe.defaultName 파일에 /etc/wsl-distribution.conf 항목이 필요합니다.

배포판을 배포하세요

WSL 사용자는 wsl --list --online 실행하여 사용 가능한 배포를 볼 수 있으며 wsl --install <distroName> 사용하여 직접 설치할 수 있습니다(<distroName> Linux 배포의 실제 이름으로 대체). 이 프로세스는 배포 매니페스트 파일에 의해 제어됩니다. 명령 옵션에 포함되도록 이 매니페스트 파일을 고객 Linux 배포판에 wsl --install 추가할 수 있습니다.

.wsl 파일 확장자로 만들고 이름을 바꾼 사용자 지정 Linux 배포 tar를 원하는 대로 배포할 수 있습니다. 다운로드가 완료되면 사용자는 명령줄에서 wsl --install --from-file <fileLocation> 사용하여 직접 설치할 수 있습니다(<fileLocation> 파일의 실제 위치로 대체). 사용자 지정 WSL 배포 파일을 열려면 .wsl 파일을 두 번 클릭하십시오.

배포 매니페스트 세부 정보

배포 매니페스트에는 .를 통해 wsl --install <distribution>설치할 수 있는 배포에 대한 메타데이터가 포함되어 있습니다.

tar 기반 Linux 배포판은 아래 형식으로 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 사용자에게 귀하의 배포판을 wsl --install에 추가합니다

모든 사용자가 WSL 배포를 사용할 수 있도록 하려면 배포 정보를 포함하도록 DistributionInfo.json 파일을 수정하는 WSL GitHub 리포지토리 끌어오기 요청을 엽니다.

이 끌어오기 요청은 WSL 팀에서 검토합니다.

기업 또는 사업 그룹의 wsl --install에 당신의 배포 포함시키기

선택한 Windows 디바이스에서 레지스트리 키를 편집하여 선택한 그룹에만 wsl --install 배포를 사용할 수 있도록 할 수도 있습니다.

레지스트리 값을 생성하여 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss에서 WSL 배포 매니페스트를 재정의할 수 있습니다.

• DistributionListUrl: 배포 매니페스트 URL을 재정의합니다.
• DistributionListUrlAppend: 해당 매니페스트 URL의 배포를 설치 가능한 배포 목록에 추가

두 레지스트리 값은 모두 문자열(REG_SZ)이며 URL 형식이어야 합니다.

WSL 릴리스 2.4.4부터 file:// 프로토콜이 지원되어 로컬 테스트를 더 쉽게 수행합니다. 필요한 형식은 file:///C:/path/to/file.

로컬로 배포 테스트

배포 tar를 테스트하려면 다음 샘플 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 하여 공식 매니페스트로 되돌릴 수 있습니다.

WSL 사용자 지정 Linux 배포 권장 사항

구성 파일 권장 사항

• 사용자 지정 배포에 /etc/wsl.conf 및 /etc/wsl-distribution.conf 구성 파일이 모두 포함되어 있는지 확인합니다. 두 파일 모두 root:root 소유해야 하며 해당 사용 권한은 0644합니다.
• oobe.command 설정을 사용하여 새 사용자를 만드는 경우 uid 및 oobe.defaultUid 모두 1000설정해야 합니다.
• 배포 구성 파일에서 oobe.defaultName 및 shortcut.icon 모두 설정해야 합니다. /etc/wsl-distribution.conf
• 루트 파일 시스템에 파일 /etc/resolv.conf 포함하지 마세요.
• /etc/passwd에 루트 사용자를 반드시 포함하세요. 이 루트 사용자의 uid는 0이어야 합니다.
• /etc/shadow암호 해시가 없어야 합니다.
• 보관 파일에 커널 또는 initramfs가 포함되어서는 안 됩니다.

시스템화된 권장 사항

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