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

아티클
11/19/2024

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

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

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

참고 항목

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

참고 항목

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

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

WSL 배포판은 Windows에서 파일 확장자를 사용하는 tar 파일로 .wsl 정의됩니다.

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

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

WSL 구성 파일 만들기

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

/etc/wsl-distribution.conf: WSL을 사용하여 처음 시작할 때 Linux 배포를 구성하는 방법을 제어하는 배포 유지 관리자가 만든 파일입니다.
/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	value	default	참고
`oobe.command`	string	`<none>`	OOBE는 기본 환경을 의미합니다. 이 명령은 사용자가 배포에서 대화형 셸을 처음 열 때 실행됩니다. 이 명령이 0이 아닌 경우 실패한 것으로 간주되며 사용자가 셸을 열 수 없습니다.
`oobe.defaultUid`	정수	`<none>`	배포가 시작되는 기본 UID입니다. 이 기능은 스크립트에서 `oobe.command` 새 사용자를 만들 때 유용합니다.
`oobe.defaultName`	string	`<none>`	배포판이 등록된 기본 이름입니다. 이 기본 이름은 다음 명령으로 바꿀 수 있습니다. `wsl.exe --install <distro> --name <name>`
`shortcut.icon`	string	기본 WSL 아이콘	배포에 대한 시작 메뉴 바로 가기의 아이콘입니다. 최대 크기가 .ico >인 형식이어야 합니다. `10MB`
'windowsterminal.profileTemplate'	string	터미널 템플릿 파일의 경로	이 배포에 대한 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/bin/deluser "$username"
    fi
  fi
done

Windows 터미널 프로필 생성

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

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

배포 작성자가 값을 true 로 설정 boot.systemd 하여 기본적으로 systemd를 사용할 수 있는지 여부를 결정합니다 false (사용 안 함).

기본적으로 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 파일을 만든 후 마지막 단계는 파일 확장명의 이름을 변경하여 파일 확장자를 파일 확장 .wsl 명으로 변경하는 .tar 것입니다. 이 파일 확장명 이름을 바꾸면 WSL 배포로 표시됩니다. TAR의 이름이 바뀐 .tar .wsl후에는 파일 탐색기 열면 파일이 Windows에 올바르게 설치됩니다(두 번 클릭). oobe.defaultName 이 두 번 클릭 환경이 /etc/wsl-distribution.conf 제대로 작동하려면 파일에 항목이 필요합니다.

WSL 배포

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

파일 확장자를 사용하여 만들고 이름을 바꾼 .wsl 사용자 지정 Linux 배포 TAR는 배포할 수 있습니다. 다운로드가 완료되면 사용자가 명령줄 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 사용자에 `wsl --install` 대해 배포판 추가

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

이 끌어오기 요청은 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

로컬 배포 테스트

배포 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 하여 공식 매니페스트로 되돌릴 수 있습니다.

모범 사례

구성 파일

/etc/wsl.conf 포함 /etc/wsl-distribution.conf 해야 합니다. 소유해야 root:root 하며 사용 권한이 있어야 합니다. 0644
새 사용자를 만드는 데 사용되는 경우 oobe.command 해당 uid는 1000해당 값으로 설정되어야 합니다 oobe.defaultUid .
oobe.defaultName 에서 shortcut.icon 지정해야 합니다. /etc/wsl-distribution.conf
/etc/resolv.conf루트 파일 시스템 포함되지 않아야 합니다.
루트 사용자가 /etc/passwd 있어야 하며 해당 uid는 0
에 암호 해시가 없어야 합니다. /etc/shadow
보관 파일에 커널 또는 initramfs가 포함되어서는 안 됩니다.

Systemd

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

다음을 통해 공유

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

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

WSL 구성 파일 만들기

WSL 배포 구성 파일 추가

Windows 터미널 프로필 생성

배포별로 로컬 설정에 대한 WSL 구성 추가

tar 파일 만들기

.wsl 파일 확장명 만들기

WSL 배포

배포 매니페스트 세부 정보

모든 WSL 사용자에 `wsl --install` 대해 배포판 추가

엔터프라이즈 또는 그룹에 배포판 `wsl --install` 추가

로컬 배포 테스트

모범 사례

구성 파일

Systemd

추가 리소스

다음을 통해 공유

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

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

WSL 구성 파일 만들기

WSL 배포 구성 파일 추가

Windows 터미널 프로필 생성

배포별로 로컬 설정에 대한 WSL 구성 추가

tar 파일 만들기

.wsl 파일 확장명 만들기

WSL 배포

배포 매니페스트 세부 정보

모든 WSL 사용자에 wsl --install 대해 배포판 추가

엔터프라이즈 또는 그룹에 배포판 wsl --install 추가

로컬 배포 테스트

모범 사례

구성 파일

Systemd

추가 리소스

모든 WSL 사용자에 `wsl --install` 대해 배포판 추가

엔터프라이즈 또는 그룹에 배포판 `wsl --install` 추가