Handleiding

Voordat je begint

Elke 64-bits x86-computer. Het installatieprogramma vraagt minstens 1,7 GB RAM en 18 GB schijfruimte; met de waarden hieronder draait het systeem comfortabel.

Hetzelfde image werkt zowel met UEFI als met het oudere BIOS. Secure Boot kan aan blijven staan.

Downloaden en controleren

Het image is één bestand, moonlightos-26.04.5-bengunur-amd64.iso, en daarnaast staat een tweede bestand met de SHA-256-controlesom. Controleer die controlesom voordat je het image wegschrijft: een download die niet compleet is, levert een USB-stick op die wel opstart en daarna op verwarrende manieren vastloopt.

Op Linux of macOS, in de map waarin je de download hebt opgeslagen:

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

Op Windows, in PowerShell: vergelijk de hash die je te zien krijgt met die in het .sha256-bestand:

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

De eerste opdracht geeft OK; de tweede geeft een hash die gelijk moet zijn aan die in het bestand. Komt er iets anders uit, dan is de download beschadigd.

26.04.5 downloaden

Het image naar een USB-stick schrijven

Het image is een hybride ISO, dus een gewone blokkopie is genoeg: je hebt geen speciaal programma nodig en dezelfde stick start op zowel UEFI- als BIOS-computers. Alles wat op de stick staat, gaat verloren. Je hebt een stick van minstens 8 GB nodig.

Zoek op Linux of macOS eerst de naam van het apparaat op (lsblk op Linux, diskutil list op macOS) en dan:

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

Controleer de apparaatnaam twee keer: dd schrijft naar precies het apparaat dat je opgeeft.

Windows

Gebruik Rufus in de stand DD-image, balenaEtcher of Ventoy. Vraagt Rufus of hij in ISO- of DD-modus moet schrijven, kies dan DD.

Opstarten van de USB-stick

Zet de computer aan met de stick erin en open het eenmalige opstartmenu (F12, F8, F2, Esc of Del, afhankelijk van de fabrikant), of zet het USB-apparaat in de firmware-instellingen vooraan in de opstartvolgorde. Aan Secure Boot hoef je niets te veranderen.

Het opstartmenu

• Try or Install MoonLightOS

  Het gewone item. Start de livesessie met de opstartanimatie.

• Try or Install MoonLightOS (safe graphics)

  Hetzelfde, maar met kernel mode-setting uit. Gebruik dit als het scherm zwart blijft of het beeld vervormd is.

• MoonLightOS in RAM (needs 6 GB+)

  Zet het hele systeem in het geheugen, zodat je de stick eruit kunt halen.

• Check this medium for defects

  Controleert elk bestand op de stick tegen de controlesommen die tijdens de build zijn vastgelegd.

• Verbose boot (no splash, logs to serial)

  Toont elke melding op het scherm en op de eerste seriële poort. Dat is de enige manier om een start te lezen die mislukt voordat er beeld is.

• UEFI firmware settings

  Start opnieuw op, rechtstreeks naar de firmware-instellingen.

De livesessie

Het eerste wat je ziet, is Instellen: kies de taal van het systeem, bevestig de toetsenbordindeling (typ in het vak om het te proberen), maak verbinding met een wifinetwerk en ga daarna rondkijken of installeren. Alles wat hier wordt ingesteld, is een echte systeeminstelling, en het installatieprogramma werkt met dezelfde keuzes.

De livesessie is het volledige systeem, ongewijzigd: hetzelfde bureaublad, dezelfde hulpprogramma's, dezelfde instellingenpagina's. De livegebruiker heet moonlight en heeft geen wachtwoord. Zolang je het installatieprogramma niet start, raakt niets van wat je hier doet de schijf.

Wil je installeren, dubbelklik dan op het bureaublad op het pictogram MoonLightOS installeren, of open Instellen opnieuw en kies Installeren.

Installeren

Het installatieprogramma is Calamares. Zeven pagina's, en dan het kopiëren naar de schijf.

1. Welkom

   De taal van het installatieprogramma en de links naar deze handleiding.

2. Locatie

   Je regio en je tijdzone; de taalinstellingen en de notatie van getallen volgen daaruit.

3. Toetsenbord

   Staat al op wat je bij Instellen hebt gekozen. Typ in het vak om het te controleren.

4. Partities

   Standaard staat Schijf wissen aan; dat maakt een ext4-bestandssysteem met een wisselbestand. btrfs, xfs en f2fs kunnen ook, en zelf partitioneren kan net zo goed. Vink Systeem versleutelen aan voor volledige schijfversleuteling met LUKS2 en kies een wachtwoordzin: die typ je bij elke start, en vergeet je hem, dan is hij niet terug te halen. Op een UEFI-computer wordt er een EFI-partitie van 512 MiB aangemaakt.

5. Gebruikers

   Je naam, de naam van de computer, een gebruikersnaam en een wachtwoord van minstens acht tekens uit twee soorten tekens. Het eerste account beheert de computer via sudo; het root-account blijft op slot, en automatisch aanmelden gebeurt alleen als je het zelf aanzet.

6. Samenvatting

   Alles wat het installatieprogramma gaat doen, in één lijst. Er is nog niets weggeschreven.

7. Installeren

   Het systeem wordt naar de schijf gekopieerd, de bootloader wordt geïnstalleerd (bij UEFI als MoonLightOS in de opstartlijst van de firmware) en de resten van de livesessie worden opgeruimd. Daarna opnieuw opstarten en de stick eruit halen.

Andere besturingssystemen op de computer worden bij de eerste start door os-prober gevonden en aan het GRUB-menu toegevoegd.

De eerste start

Een geïnstalleerd systeem begint als een exacte kopie van het image waar alle andere installaties ook uit komen. Alles wat alleen van deze computer mag zijn, wordt bij de eerste start aangemaakt, nog voordat het aanmeldscherm verschijnt, door een dienst die zich daarna zelf uitschakelt:

• een nieuwe machine-ID, zodat niemand die het netwerk in de gaten houdt, twee installaties aan elkaar kan knopen;
• nieuwe SSH-hostsleutels, want een sleutel die iedereen deelt die het image heeft gedownload, maakt het controleren van hosts zinloos;
• het GRUB-menu, nu de echte schijven en de andere besturingssystemen daarop in zicht zijn;
• een initramfs die opnieuw is gebouwd voor de hardware die er echt in zit, waardoor die kleiner is en de opstartanimatie eerder verschijnt;
• de caches voor pictogrammen, lettertypen en het bureaublad, zodat de eerste aanmelding niet traag is;
• de firewall, die weer wordt aangezet.

De uitvoer komt in /var/log/moonlight-firstboot.log. Daarna verschijnt het aanmeldscherm, en na de eerste aanmelding het venster Welkom.

De eerste stappen

• Kies een uiterlijk

  Donker of licht, meteen in Welkom. Al het andere zit in MoonLight Tweaks: de indeling van het bureaublad, de achtergrond, het schema en de widgets.

• Stuurprogramma's

  Welkom → Stuurprogramma's opent het Stuurprogrammabeheer. Zit er een NVIDIA-kaart in de computer, dan staat het stuurprogramma van de fabrikant op de ISO, dus het werkt ook zonder internetverbinding.

• Programma's

  De winkel toont snaps, de pakketbron van Ubuntu en Flathub bij elkaar. Thunderbird, Steam, Spotify en veel meer vind je met één zoekopdracht.

• Vingerafdruk en gezicht

  Ga naar Welkom → Vingerafdruk, of naar Systeeminstellingen → Je account, om een vingerafdruk te registreren of gezichtsontgrendeling in te stellen.

• Back-ups

  Timeshift maakt volgens een schema momentopnamen van het systeem. Stel het in voordat je het nodig hebt.

• Beveiliging

  Systeeminstellingen → Beveiliging laat zien wat deze computer wel en niet beschermt, met bij elke regel de knop die het regelt.

• Ontwikkelpakketten

  Virtuele machines, PHP met databases en LaTeX: elk één klik in Welkom, geïnstalleerd uit de pakketbron die al is ingesteld.

• Windows-programma's

  Open Windows-apps één keer: het maakt Wine gereed met DXVK, VKD3D, lettertypen en runtimes. Daarna openen .exe-bestanden gewoon.

Virtuele machines

VirtualBox

Bij VirtualBox moet je drie standaardinstellingen aanpassen, anders start dit image er helemaal niet. De fout lijkt op een geheugenprobleem, maar is het niet: GRUB schakelt over naar een grafische modus om het menu in de stijl van het systeem te tekenen, en met de 16 MB videogeheugen die VirtualBox standaard geeft, mislukt dat met de melding “Out of memory. You need to load the kernel first.”

Vanaf de opdrachtregel:

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

VirtualBox zet het label “Ubuntu” op het medium, omdat het er een map /casper op aantreft. Dat label bestaat alleen in de interface van VirtualBox; het medium zelf meldt zich als MoonLightOS. Zet het gasttype toch op Ubuntu, want daarmee kiest VirtualBox de juiste chipset en de juiste grafische standaardinstellingen.

QEMU

UEFI, zoals de meeste computers opstarten. Maak eerst de beschrijfbare firmwarevariabelen en een doelschijf aan:

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

Met Secure Boot echt aan, via de firmware waarin de sleutels van Microsoft zijn opgenomen. Zodra het systeem loopt, meldt mokutil --sb-state SecureBoot enabled, en Instellingen → Over zegt hetzelfde:

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

Het oudere BIOS: de ISO is hybride, dus hetzelfde bestand start ook op de oude manier:

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

Wil je de bewering over 2 GB zelf testen, start dan zonder versnelling en met het minimum aan geheugen, en kijk in de livesessie of zram als swap verschijnt en of de geheugendruk laag blijft:

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

De gasthulpprogramma's voor VirtualBox, QEMU/SPICE en VMware staan al op het image; daardoor schaalt het beeld mee en wordt het klembord gedeeld.

Sneltoetsen

De volledige tabel staat op de pagina Mogelijkheden. Deze zijn het waard om op dag één te leren:

De volledige tabel

Problemen oplossen

• Het scherm blijft zwart na het opstartmenu

  Kies het item met veilige grafische instellingen. Komt het systeem daarmee wel op, installeer dan vanuit die sessie en zet daarna op de pagina Stuurprogramma's het stuurprogramma van de fabrikant aan.

• “Out of memory. You need to load the kernel first.”

  Een VirtualBox-machine met 16 MB videogeheugen. Geef er 128 MB en zet 3D-versnelling aan; zie Virtuele machines hierboven.

• Het bureaublad voelt traag

  Kijk in Instellingen → Over welke OpenGL-renderer actief is. Gebeurt de weergave in software, dan gaan de animaties bij het aanmelden automatisch uit; via Tweaks → Prestaties zet je ze zelf uit.

• De stick start, maar loopt daarna op verwarrende manieren vast

  Kies Check this medium for defects in het opstartmenu en controleer de SHA-256-controlesom van de download.

• Geen wifi

  Open de pagina Stuurprogramma's: het stuurprogramma van Broadcom staat op het image. Voor andere adapters toont het netwerkmenu wat de kernel heeft gevonden.

• De vingerafdruklezer wordt niet gevonden

  Open Vingerafdruk. Dat noemt de merknaam van de sensor, zegt of die rechtstreeks wordt ondersteund, zelf op de chip vergelijkt of een binair bestand van de fabrikant nodig heeft, en legt uit wat je eraan kunt doen.

• De logboeken lezen

  Waar de start over klaagde, het logboek van het aanmeldbeheer, het logboek van de eerste start en de naam van het actieve opstartthema:

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

Voor een foutrapport: met Over → Rapport kopiëren zet je de uitgave en de hardware op het klembord, en moonlight-selftest toont wat het bureaublad werkelijk doet.

moonlight-selftest | less

Zelf bouwen

De hele distributie zit in één repository: de vormgeving komt uit één bronlogo, de thema's worden uit één palet gegenereerd, en één script maakt er een opstartbare ISO van die met Secure Boot werkt. Je hebt Docker nodig (op welk besturingssysteem dan ook, want de build draait in een container) en ongeveer 25 GB vrije ruimte.

De ISO komt in out/ te staan, met een SHA-256-controlesom ernaast. Op Windows start je het script vanuit Git Bash, of je gebruikt build.ps1.

Hoe de build is ingedeeld

Voordat de ISO wordt gemaakt, voert de build meer dan 120 verplichte controles uit binnen het image: de kernel, de ondertekende shim, beide thema's, elke MoonTool, de codecs, de wifistuurprogramma's, de vertalingen, en of gezichtsontgrendeling en het noodwachtwoord uit staan. Zakt er één controle, dan stopt de build. De tijdelijke ruimte is een Docker-volume en geen bind mount, omdat bestandseigendom, symbolische koppelingen en apparaatbestanden een bind mount op Windows of macOS niet overleven.

Aanpassen

• De identiteit van de uitgave

  In config/moonlight.conf staat elke tekst die de distributie bepaalt.

• Vormgeving

  Vervang het bronlogo of een achtergrond en voer tools/gen-branding.py opnieuw uit: de opstartanimatie, GRUB, het aanmeldscherm, de pictogrammen en de vormgeving van het installatieprogramma worden dan allemaal opnieuw gemaakt.

• Kleuren

  In tools/gen-themes.py staan één donker en één licht palet, en daaruit maakt het script met dezelfde regels beide complete thema's.

• Geïnstalleerde pakketten

  packages/*.list, één pakket per regel, geïnstalleerd in de volgorde van de bestandsnamen; in 99-purge.list staat wat er daarna weer af gaat.

• Standaardinstellingen van het bureaublad

  rootfs/etc/dconf/db/moonlight.d/, in de keyfile-indeling van dconf. Dit zijn standaardwaarden en geen sloten: een gebruiker kan ze allemaal wijzigen.

• Snel opnieuw bouwen

  Heb je iets in rootfs/ of in de pakketlijsten veranderd, dan herhaalt build.sh rootfs de chroot-fase op de bewaarde basis en verpakt build.sh image de ISO opnieuw; build.sh finish is bedoeld voor werk aan het opstartmenu.

Hulp krijgen en fouten melden

Een nuttig rapport vertelt wat je verwachtte, wat er in plaats daarvan gebeurde en op welke computer. Dat derde deel maakt MoonLightOS eenvoudig:

• Over MoonLightOS → Rapport kopiëren zet de uitgave, de hardware, de grafische renderer en de staat van Secure Boot als tekst op het klembord.
• moonlight-selftest toont welke thema-instellingen in gebruik zijn, of het stijlblad van de shell goed is geladen, welk grafisch stuurprogramma actief is en welke diensten zijn mislukt.
• Gaat het om een probleem bij het opstarten, dan schrijft het item Verbose boot elke melding naar het scherm en naar de eerste seriële poort.
• Voor het installatieprogramma: /var/log/moonlight-firstboot.log op het geïnstalleerde systeem, en journalctl -b -p warning.

Waar je het naartoe stuurt

Een openbare issuetracker en een plek voor ondersteuning worden hier aangekondigd. Bewaar je rapport tot die tijd: alles wat erin moet staan, komt uit de twee hulpprogramma's hierboven.