안내서

시작하기 전에

64비트 x86 컴퓨터면 됩니다. 설치 프로그램은 메모리 1.7 GB와 디스크 공간 18 GB 이상을 요구하며, 아래 값은 시스템이 넉넉하게 돌아가는 기준입니다.

같은 이미지로 UEFI와 옛 BIOS를 모두 지원합니다. Secure Boot는 켜 둔 채로 두어도 됩니다.

내려받기와 검증

이미지는 moonlightos-26.04.5-bengunur-amd64.iso 파일 하나이고, 그 옆의 다른 파일에 SHA-256 체크섬이 들어 있습니다. 이미지를 쓰기 전에 체크섬을 확인하세요. 내려받다 만 파일로 만든 USB는 부팅은 되지만 그다음부터 영문 모를 방식으로 실패합니다.

Linux나 macOS에서, 내려받은 파일이 있는 폴더에서 실행합니다.

sha256sum -c moonlightos-26.04.5-bengunur-amd64.iso.sha256

Windows에서는 PowerShell로 실행한 뒤, 찍힌 해시를 .sha256 파일의 값과 견주어 봅니다.

Get-FileHash .\moonlightos-26.04.5-bengunur-amd64.iso -Algorithm SHA256
Get-Content .\moonlightos-26.04.5-bengunur-amd64.iso.sha256

첫 번째 명령은 OK를 찍습니다. 두 번째는 해시를 찍는데, 파일에 적힌 값과 같아야 합니다. 그 밖의 결과라면 내려받은 파일이 상한 것입니다.

26.04.5 내려받기

USB 메모리에 이미지 쓰기

하이브리드 ISO라서 그냥 블록 단위로 복사하면 됩니다. 특별한 도구가 필요 없고, 같은 USB가 UEFI 컴퓨터와 BIOS 컴퓨터 양쪽에서 부팅됩니다. USB에 있던 내용은 모두 지워집니다. 용량은 8 GB 이상이어야 합니다.

Linux나 macOS에서는 장치 이름부터 확인하고(Linux는 lsblk, macOS는 diskutil list) 다음을 실행합니다.

sudo dd if=moonlightos-26.04.5-bengunur-amd64.iso of=/dev/sdX bs=4M status=progress oflag=direct conv=fsync

sudo dd if=moonlightos-26.04.5-bengunur-amd64.iso of=/dev/rdiskN bs=4m   # macOS

장치 이름은 꼭 두 번 확인하세요. dd는 알려 준 장치에 그대로 씁니다.

Windows

DD 이미지 모드의 Rufus나 balenaEtcher, Ventoy를 쓰세요. Rufus가 ISO 모드로 쓸지 DD 모드로 쓸지 물으면 DD를 고르면 됩니다.

USB 메모리로 부팅하기

USB를 꽂은 채 컴퓨터를 켜고 일회용 부팅 메뉴를 엽니다(제조사에 따라 F12, F8, F2, Esc, Del 가운데 하나). 아니면 펌웨어 설정에서 USB 장치를 첫 부팅 장치로 지정합니다. Secure Boot는 건드리지 않아도 됩니다.

부팅 메뉴

• Try or Install MoonLightOS

  보통 고르는 항목입니다. 부팅 애니메이션과 함께 라이브 세션을 띄웁니다.

• Try or Install MoonLightOS (safe graphics)

  같은 항목이되 커널 모드 설정을 끕니다. 화면이 까맣게만 있거나 화면이 깨질 때 쓰세요.

• MoonLightOS in RAM (needs 6 GB+)

  시스템 전체를 메모리로 올려 두므로, 그 뒤에는 USB를 빼도 됩니다.

• Check this medium for defects

  빌드할 때 적어 둔 체크섬으로 USB의 모든 파일을 맞춰 봅니다.

• Verbose boot (no splash, logs to serial)

  모든 메시지를 화면과 첫 번째 직렬 포트에 보여 줍니다. 화면이 켜지기도 전에 실패하는 부팅을 들여다보는 유일한 방법입니다.

• UEFI firmware settings

  펌웨어 설정으로 다시 시작합니다.

라이브 세션

가장 먼저 초기 설정 마법사가 나옵니다. 시스템 언어를 고르고, 키보드 배치를 확인하고(입력란에 쳐 보면 됩니다), Wi-Fi에 연결한 다음, 둘러볼지 설치할지 정합니다. 여기서 정한 것은 모두 진짜 시스템 설정이고, 설치 프로그램도 같은 선택을 씁니다.

라이브 세션은 손대지 않은 완전한 시스템 그대로입니다. 같은 데스크톱, 같은 도구, 같은 설정 페이지입니다. 라이브 사용자 이름은 moonlight이고 암호는 없습니다. 설치 프로그램을 돌리기 전에는 여기서 무엇을 하든 디스크를 건드리지 않습니다.

설치하려면 바탕에 있는 Install MoonLightOS를 두 번 누르거나, 초기 설정 마법사를 다시 열어 설치를 고르면 됩니다.

설치

설치 프로그램은 Calamares입니다. 일곱 쪽을 지나면 디스크로 복사가 시작됩니다.

1. 환영

   설치 프로그램의 언어와 이 안내서로 가는 링크.

2. 지역

   지역과 표준 시간대. 로캘과 숫자 표기는 여기서 따라옵니다.

3. 키보드

   마법사에서 고른 대로 이미 맞춰져 있습니다. 입력란에 쳐 보며 확인하세요.

4. 파티션

   기본은 디스크 지우기이며 스왑 파일이 딸린 ext4 파일 시스템을 만듭니다. btrfs와 xfs, f2fs도 고를 수 있고 직접 나눌 수도 있습니다. 시스템 암호화를 선택하면 LUKS2로 디스크 전체를 암호화하며 암호 문구를 정합니다. 이 문구는 켤 때마다 입력해야 하고, 잊어버리면 되살릴 수 없습니다. UEFI 컴퓨터에서는 512 MiB짜리 EFI 파티션을 만듭니다.

5. 사용자

   이름과 컴퓨터 이름, 사용자 이름, 그리고 두 가지 문자 종류를 섞은 여덟 자 이상의 암호를 정합니다. 첫 번째 계정이 sudo로 컴퓨터를 관리하고, root 계정은 잠긴 채로 두며, 직접 켜지 않는 한 자동 로그인도 없습니다.

6. 요약

   설치 프로그램이 이제 할 일을 한 목록으로 보여 줍니다. 아직 아무것도 쓰지 않은 상태입니다.

7. 설치

   시스템을 디스크로 옮기고, 부트로더를 설치하고(UEFI에서는 펌웨어의 부팅 목록에 MoonLightOS로 올라갑니다), 라이브 세션의 흔적을 지웁니다. 끝나면 다시 시작하고 USB를 빼세요.

컴퓨터에 있는 다른 운영체제는 첫 부팅 때 os-prober가 찾아내 GRUB 메뉴에 더해 줍니다.

첫 부팅

설치한 시스템은 다른 모든 설치와 똑같은 이미지의 사본으로 출발합니다. 이 컴퓨터만의 것이어야 하는 값들은 로그인 화면이 나오기 전, 첫 부팅 때 만들어집니다. 그 일을 맡은 서비스는 끝나면 스스로 꺼집니다.

• 새 머신 ID. 네트워크를 지켜보는 쪽에서 두 설치를 이어 붙이지 못하게 합니다.
• 새 SSH 호스트 키. 이미지를 내려받은 모두가 같은 키를 쓰면 호스트 확인이 아무 의미가 없기 때문입니다.
• GRUB 메뉴. 이제 진짜 디스크와 거기 담긴 다른 운영체제가 보이기 때문입니다.
• 실제로 달린 하드웨어에 맞춰 다시 만든 initramfs. 더 작아지고 부팅 애니메이션도 더 일찍 나옵니다.
• 아이콘과 글꼴, 바탕 화면 캐시. 첫 로그인이 느려지지 않게 합니다.
• 방화벽. 다시 켭니다.

그 출력은 /var/log/moonlight-firstboot.log에 적힙니다. 그다음 로그인 화면이 나오고, 처음 로그인하면 환영 창이 뜹니다.

먼저 할 일

• 겉모습 고르기

  어둡게와 밝게는 환영합니다에서 바로 고릅니다. 나머지는 모두 MoonLight Tweaks에 있습니다. 바탕 배치와 배경 그림, 전환 시각, 위젯입니다.

• 드라이버

  환영합니다 → 드라이버에서 드라이버 관리자가 열립니다. NVIDIA 그래픽을 단 컴퓨터라면 독점 드라이버가 ISO에 있어 인터넷 없이도 됩니다.

• 소프트웨어

  스토어가 snap과 Ubuntu 저장소, Flathub을 함께 보여 줍니다. Thunderbird와 Steam, Spotify를 비롯해 대부분 검색 한 번이면 됩니다.

• 지문과 얼굴

  환영합니다 → 지문, 또는 시스템 설정 → 내 계정에서 지문을 등록하거나 얼굴 인식 잠금 해제를 설정합니다.

• 백업

  Timeshift가 정해진 때마다 시스템 스냅숏을 뜹니다. 필요해지기 전에 미리 맞춰 두세요.

• 보안

  시스템 설정 → 보안에서 이 컴퓨터의 무엇이 지켜지고 무엇이 지켜지지 않는지 보여 주며, 각 줄에 고쳐 주는 단추가 달려 있습니다.

• 개발자 묶음

  가상 머신과 PHP·데이터베이스, LaTeX은 환영합니다에서 각각 한 번 누르면 되고, 이미 맞춰 둔 저장소에서 설치됩니다.

• Windows 프로그램

  Windows 앱을 한 번만 열어 두세요. Wine과 DXVK, VKD3D, 글꼴, 런타임까지 준비해 둡니다. 그다음부터는 .exe 파일이 그냥 열립니다.

가상 머신

VirtualBox

VirtualBox는 기본값에서 세 가지를 바꿔야 하며, 그러지 않으면 이 이미지가 아예 뜨지 않습니다. 실패한 모습이 메모리 부족처럼 보이지만 사실은 아닙니다. GRUB이 테마가 입혀진 메뉴를 그리려고 그래픽 모드로 넘어가는데, VirtualBox의 기본 비디오 메모리 16 MB로는 그것이 실패하면서 「Out of memory. You need to load the kernel first.」라는 메시지가 뜹니다.

명령줄에서는 다음과 같이 합니다.

VBoxManage modifyvm "MoonLightOS" \
    --ostype Ubuntu24_LTS_64 --memory 4096 --cpus 4 \
    --vram 128 --graphicscontroller vmsvga --accelerate3d on \
    --boot1 dvd --boot2 disk

VirtualBox가 이 매체를 「Ubuntu」라고 적는 것은 안에서 /casper 폴더를 찾기 때문입니다. 이는 VirtualBox 화면의 이름표일 뿐이고, 매체 자체는 MoonLightOS로 알립니다. 그래도 게스트 종류는 Ubuntu로 두세요. 그래야 알맞은 칩셋과 그래픽 기본값이 잡힙니다.

QEMU

대부분의 컴퓨터가 부팅하는 방식인 UEFI입니다. 먼저 쓰기 가능한 펌웨어 변수와 대상 디스크를 만듭니다.

cp /usr/share/OVMF/OVMF_VARS.fd .
qemu-img create -f qcow2 disk.qcow2 30G
qemu-system-x86_64 \
  -enable-kvm -m 4096 -smp 4 \
  -machine q35 -cpu host \
  -device virtio-vga-gl -display gtk,gl=on \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE.fd \
  -drive if=pflash,format=raw,file=OVMF_VARS.fd \
  -drive file=moonlightos-26.04.5-bengunur-amd64.iso,media=cdrom \
  -drive file=disk.qcow2,if=virtio

Microsoft 키를 등록한 펌웨어를 써서 Secure Boot를 실제로 켠 경우입니다. 부팅한 뒤 mokutil --sb-state가 SecureBoot enabled라고 알리고, 설정 → MoonLightOS 정보도 같은 결과를 보여 줍니다.

cp /usr/share/OVMF/OVMF_VARS_4M.ms.fd OVMF_VARS.fd
qemu-system-x86_64 \
  -enable-kvm -m 4096 -smp 4 -machine q35,smm=on -cpu host \
  -global driver=cfi.pflash01,property=secure,value=on \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.secboot.fd \
  -drive if=pflash,format=raw,file=OVMF_VARS.fd \
  -drive file=moonlightos-26.04.5-bengunur-amd64.iso,media=cdrom

옛 BIOS입니다. ISO가 하이브리드라서 같은 파일이 옛 방식으로도 부팅됩니다.

qemu-system-x86_64 -enable-kvm -m 2048 -cdrom moonlightos-26.04.5-bengunur-amd64.iso

2 GB로 된다는 말을 확인하려면 가속을 끄고 최소 메모리로 띄운 다음, 라이브 세션에서 zram이 스왑으로 잡혔는지와 메모리 압박이 낮게 유지되는지 보면 됩니다.

qemu-system-x86_64 -enable-kvm -m 2048 -smp 2 -vga std -cdrom moonlightos-26.04.5-bengunur-amd64.iso

# in the live session:
free -h                      # zram appears as swap
swapon --show                # /dev/zram0, zstd
cat /proc/pressure/memory    # "some avg10" under about 10 means it is keeping up
systemctl is-active earlyoom

VirtualBox와 QEMU/SPICE, VMware용 게스트 도구는 이미 이미지에 들어 있고, 화면 크기 맞춤과 클립보드 공유가 바로 여기서 나옵니다.

단축키

전체 표는 기능 페이지에 있습니다. 첫날 익혀 둘 만한 것은 다음과 같습니다.

전체 표

문제 해결

• 부팅 메뉴를 지나면 화면이 까맣게만 있습니다

  safe graphics 항목을 고르세요. 그걸로 뜬다면 거기서 설치한 뒤, 드라이버 페이지에서 독점 드라이버를 켜면 됩니다.

• 「Out of memory. You need to load the kernel first.」

  비디오 메모리가 16 MB인 VirtualBox입니다. 128 MB로 올리고 3D 가속을 켜세요. 위의 가상 머신 항목을 보면 됩니다.

• 데스크톱이 굼뜨게 느껴집니다

  설정 → MoonLightOS 정보에서 OpenGL 렌더러를 확인하세요. 소프트웨어 렌더링이면 로그인할 때 애니메이션이 저절로 꺼지고, Tweaks → 성능에서 직접 끌 수도 있습니다.

• USB는 뜨는데 그다음부터 영문 모를 방식으로 실패합니다

  부팅 메뉴에서 Check this medium for defects를 돌리고, 내려받은 파일의 SHA-256 체크섬도 확인하세요.

• Wi-Fi가 안 잡힙니다

  드라이버 페이지를 여세요. Broadcom 드라이버는 이미지에 들어 있습니다. 다른 어댑터라면 네트워크 메뉴에서 커널이 무엇을 찾았는지 볼 수 있습니다.

• 지문 인식기를 찾지 못합니다

  지문 인식을 여세요. 센서 제조사를 알려 주고, 기본 지원인지 칩 안에서 대조하는 방식인지 제조사 바이너리를 쓰는 방식인지 짚어 주며, 무엇을 할 수 있는지 설명합니다.

• 로그 읽기

  부팅할 때 무엇이 문제였는지, 로그인 관리자의 로그, 첫 부팅 로그, 그리고 지금 쓰는 부팅 테마의 이름을 볼 수 있습니다.

journalctl -b -p warning          # what the boot complained about
journalctl -b -u lightdm
cat /var/log/moonlight-firstboot.log
plymouth-set-default-theme        # should print: moonlightos

버그를 신고할 때는 MoonLightOS 정보 → 보고서 복사로 릴리스와 하드웨어 정보가 클립보드에 담기고, moonlight-selftest가 데스크톱이 실제로 무엇을 하고 있는지 찍어 줍니다.

moonlight-selftest | less

직접 빌드하기

배포판 전체가 저장소 하나입니다. 그래픽 자산은 원본 로고 하나에서 뽑아내고, 테마는 팔레트 하나에서 만들며, 스크립트 하나가 그 모두를 Secure Boot에서도 도는 부팅 가능한 ISO로 바꿔 놓습니다. 필요한 것은 Docker(빌드가 컨테이너 안에서 도니 운영체제는 가리지 않습니다)와 25 GB쯤의 빈 공간입니다.

ISO는 out/에 쓰이고 그 옆에 SHA-256 체크섬이 놓입니다. Windows에서는 Git Bash에서 돌리거나 build.ps1을 쓰세요.

빌드는 어떻게 짜여 있나

ISO를 만들기 전에 빌드는 이미지 안에서 120개가 넘는 필수 검사를 돌립니다. 커널과 서명된 shim, 두 테마, MoonTools의 모든 도구, 코덱, Wi-Fi 드라이버, 번역, 그리고 얼굴 인식 잠금 해제와 비상 암호가 꺼져 있는지까지 봅니다. 하나라도 실패하면 빌드가 멈춥니다. 작업 공간으로 bind mount가 아니라 Docker 볼륨을 쓰는데, Windows와 macOS의 bind mount에서는 파일 소유권과 심볼릭 링크, 장치 노드가 살아남지 못하기 때문입니다.

고쳐 쓰기

• 릴리스 정보

  config/moonlight.conf에 이 배포판을 규정하는 문구가 모두 들어 있습니다.

• 그래픽 자산

  원본 로고나 배경 그림을 갈아 끼우고 tools/gen-branding.py를 다시 돌리면, 부팅 애니메이션과 GRUB, 로그인 화면, 아이콘, 설치 프로그램 그림이 모두 다시 만들어집니다.

• 색

  tools/gen-themes.py에 어두운 팔레트와 밝은 팔레트가 하나씩 들어 있고, 같은 규칙으로 완성된 테마 두 벌을 만들어 냅니다.

• 설치할 패키지

  packages/*.list에 한 줄에 하나씩 적고 파일 이름 순서대로 설치합니다. 나중에 지울 것은 99-purge.list에 적습니다.

• 데스크톱 기본값

  rootfs/etc/dconf/db/moonlight.d/에 dconf의 keyfile 형식으로 적습니다. 잠금이 아니라 기본값이므로 사용자가 얼마든지 바꿀 수 있습니다.

• 빠르게 다시 빌드하기

  rootfs/나 패키지 목록을 고친 뒤에는 build.sh rootfs가 캐시된 기반 위에서 chroot 단계만 다시 하고, build.sh image가 ISO를 다시 묶습니다. build.sh finish는 부팅 메뉴를 손볼 때 씁니다.

도움 받기와 버그 신고

쓸모 있는 신고에는 무엇을 기대했는지, 대신 무슨 일이 일어났는지, 그리고 어떤 컴퓨터에서 그랬는지가 들어 있습니다. 세 번째는 MoonLightOS가 쉽게 만들어 둡니다.

• MoonLightOS 정보 → 보고서 복사를 누르면 릴리스와 하드웨어, 그래픽 렌더러, Secure Boot 상태가 텍스트로 클립보드에 담깁니다.
• moonlight-selftest는 지금 적용된 테마 설정, 셸 스타일시트가 제대로 올라왔는지, 어느 그래픽 드라이버가 돌고 있는지, 어떤 서비스가 실패했는지 찍어 줍니다.
• 부팅 문제라면 Verbose boot 항목이 모든 메시지를 화면과 첫 번째 직렬 포트에 적습니다.
• 설치 프로그램 쪽은 설치한 시스템의 /var/log/moonlight-firstboot.log와 journalctl -b -p warning을 보면 됩니다.

어디로 보내나

공개 이슈 트래커와 지원 창구는 준비되는 대로 여기에 알리겠습니다. 그때까지는 신고 내용을 간직해 두세요. 거기 담겨야 할 것은 위의 두 도구에서 모두 나옵니다.