Guida

Prima di iniziare

Qualsiasi computer x86 a 64 bit. L'installatore richiede almeno 1,7 GB di RAM e 18 GB di spazio su disco; i valori qui sotto sono quelli con cui il sistema funziona senza affanno.

La stessa immagine supporta sia UEFI sia il BIOS tradizionale. Secure Boot può restare attivo.

Scaricare e verificare

L'immagine è un unico file, moonlightos-26.04.5-bengunur-amd64.iso, e un secondo file accanto contiene il suo checksum SHA-256. Verifica il checksum prima di scrivere l'immagine: un download incompleto produce una chiavetta che si avvia e poi si blocca in modi difficili da interpretare.

Su Linux o macOS, nella cartella in cui hai salvato il download:

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

Su Windows, in PowerShell, confronta l'hash stampato con quello contenuto nel file .sha256:

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

Il primo comando stampa OK; il secondo stampa un hash che deve coincidere con quello nel file. Qualsiasi altro risultato significa che il download è danneggiato.

Scarica la 26.04.5

Scrivere l'immagine su una chiavetta USB

L'immagine è una ISO ibrida, quindi basta una semplice copia a blocchi: non serve nessun programma particolare, e la stessa chiavetta si avvia sia sui computer UEFI sia su quelli con BIOS. Tutto ciò che c'è sulla chiavetta viene cancellato. Serve una chiavetta da almeno 8 GB.

Su Linux o macOS, individua prima il nome del dispositivo (lsblk su Linux, diskutil list su macOS), poi:

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

Controlla due volte il nome del dispositivo: dd scrive su qualunque dispositivo gli venga indicato.

Windows

Usa Rufus in modalità immagine DD, balenaEtcher oppure Ventoy. Se Rufus chiede se scrivere in modalità ISO o DD, scegli DD.

Avviare dalla chiavetta

Accendi il computer con la chiavetta inserita e apri il menu di avvio temporaneo (F12, F8, F2, Esc o Canc, a seconda del produttore), oppure imposta il dispositivo USB come primo dispositivo di avvio nelle impostazioni del firmware. Non serve modificare Secure Boot.

Il menu di avvio

• Try or Install MoonLightOS

  La voce normale. Avvia la sessione live con l'animazione di avvio.

• Try or Install MoonLightOS (safe graphics)

  La stessa cosa, ma con il kernel mode-setting disattivato. Usala se lo schermo resta nero o l'immagine è disturbata.

• MoonLightOS in RAM (needs 6 GB+)

  Copia tutto il sistema in memoria, così la chiavetta si può togliere.

• Check this medium for defects

  Verifica ogni file della chiavetta confrontandolo con i checksum registrati durante la build.

• Verbose boot (no splash, logs to serial)

  Mostra ogni messaggio sullo schermo e sulla prima porta seriale: l'unico modo per leggere un avvio che fallisce prima che lo schermo sia disponibile.

• UEFI firmware settings

  Riavvia nelle impostazioni del firmware.

La sessione live

La prima cosa che vedi è la configurazione iniziale: scegli la lingua del sistema, conferma la disposizione della tastiera (scrivi nella casella per provarla), collegati a una rete Wi-Fi e poi decidi se dare un'occhiata o installare. Tutto ciò che imposta è una vera impostazione di sistema, e l'installatore riusa le stesse scelte.

La sessione live è il sistema completo, senza modifiche: lo stesso desktop, gli stessi strumenti, le stesse pagine delle impostazioni. L'utente live si chiama moonlight e non ha password. Niente di ciò che fai qui tocca il disco finché non avvii l'installatore.

Per installare, fai doppio clic su Installa MoonLightOS sulla scrivania, oppure riapri la configurazione iniziale e scegli Installa.

Installare

L'installatore è Calamares. Sette pagine, poi la copia sul disco.

1. Benvenuto

   La lingua dell'installatore e i collegamenti a questa guida.

2. Posizione

   La tua zona e il fuso orario; da questi derivano le impostazioni locali e il formato dei numeri.

3. Tastiera

   Già impostata su ciò che hai scelto nella configurazione iniziale. Scrivi nella casella per controllare.

4. Partizioni

   Cancella il disco è la scelta predefinita e crea un file system ext4 con un file di swap; sono disponibili anche btrfs, xfs e f2fs, così come il partizionamento manuale. Spunta Cifra il sistema per la cifratura dell'intero disco con LUKS2 e scegli una passphrase: la digiterai a ogni avvio e non si può recuperare se la dimentichi. Su un computer UEFI viene creata una partizione EFI da 512 MiB.

5. Utenti

   Il tuo nome, il nome del computer, un nome utente e una password di almeno otto caratteri di due tipi diversi. Il primo account amministra il computer tramite sudo; l'account root resta bloccato e non c'è accesso automatico, a meno che tu non lo attivi.

6. Riepilogo

   Tutto ciò che l'installatore sta per fare, in un unico elenco. Non è ancora stato scritto nulla.

7. Installazione

   Il sistema viene copiato sul disco, il boot loader viene installato (come MoonLightOS nell'elenco di avvio del firmware, su UEFI) e i residui della sessione live vengono rimossi. Poi riavvia e togli la chiavetta.

Gli altri sistemi operativi presenti sul computer vengono riconosciuti da os-prober al primo avvio e aggiunti al menu di GRUB.

Il primo avvio

Un sistema appena installato nasce come copia esatta dell'immagine da cui proviene ogni altra installazione. Tutto ciò che deve essere unico per questo computer viene creato al primo avvio, prima che compaia la schermata di accesso, da un servizio che poi si disattiva da solo:

• un nuovo identificativo della macchina, così nessuno che osservi la rete può collegare due installazioni;
• nuove chiavi SSH dell'host, perché una chiave condivisa da tutti quelli che hanno scaricato l'immagine renderebbe inutile la verifica dell'host;
• il menu di GRUB, ora che si vedono i dischi reali e gli altri sistemi operativi che contengono;
• un initramfs ricostruito per l'hardware effettivamente presente, così è più piccolo e l'animazione di avvio compare prima;
• le cache di icone, caratteri e scrivania, così il primo accesso non è lento;
• il firewall, riattivato.

Il suo output viene scritto in /var/log/moonlight-firstboot.log. Poi compare la schermata di accesso e, dopo il primo accesso, la finestra di benvenuto.

I primi passi

• Scegli l'aspetto

  Scuro o chiaro, direttamente da Benvenuto. Tutto il resto è in MoonLight Tweaks: la disposizione della scrivania, lo sfondo, l'orario del tema e i widget.

• Driver

  Benvenuto → Driver apre il Gestore driver. Su un computer con scheda NVIDIA il driver proprietario è nella ISO, quindi funziona anche senza connessione a internet.

• Software

  Lo store elenca insieme gli snap, il repository di Ubuntu e Flathub. Thunderbird, Steam, Spotify e molti altri si trovano con una ricerca.

• Impronta e volto

  Benvenuto → Impronta digitale, oppure Impostazioni di sistema → Il tuo account, per registrare un'impronta o configurare lo sblocco con il volto.

• Backup

  Timeshift crea istantanee programmate del sistema. Configuralo prima di averne bisogno.

• Sicurezza

  Impostazioni di sistema → Sicurezza mostra che cosa protegge o non protegge questo computer, con accanto a ogni riga il pulsante per rimediare.

• Pacchetti per sviluppatori

  Macchine virtuali, PHP con i database e LaTeX: un clic ciascuno da Benvenuto, installati dal repository già configurato.

• Programmi per Windows

  Apri App Windows una volta: prepara Wine con DXVK, VKD3D, font e runtime. Da quel momento i file .exe si aprono e basta.

Macchine virtuali

VirtualBox

In VirtualBox vanno cambiate tre impostazioni rispetto ai valori predefiniti, altrimenti l'immagine non si avvia affatto. L'errore sembra un problema di memoria ma non lo è: GRUB passa a una modalità grafica per disegnare il menu con il tema, e con i 16 MB di memoria video predefiniti di VirtualBox l'operazione fallisce con il messaggio “Out of memory. You need to load the kernel first.”

Da riga di comando:

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

VirtualBox etichetta il supporto come “Ubuntu” perché vi trova una cartella /casper. È solo un'etichetta dell'interfaccia di VirtualBox; il supporto si identifica come MoonLightOS. Imposta comunque il tipo di sistema guest su Ubuntu, perché seleziona il chipset e le impostazioni grafiche giuste.

QEMU

UEFI, cioè il modo in cui si avvia la maggior parte dei computer. Crea prima le variabili del firmware scrivibili e un disco di destinazione:

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

Con Secure Boot davvero attivo, usando il firmware con le chiavi Microsoft registrate. Una volta avviato, mokutil --sb-state riporta SecureBoot enabled, e lo stesso fa Impostazioni → Informazioni:

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 tradizionale: la ISO è ibrida, quindi lo stesso file si avvia anche alla vecchia maniera:

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

Per mettere alla prova i 2 GB, avvia senza accelerazione e con la memoria minima, poi nella sessione live controlla che zram compaia come swap e che la pressione sulla memoria resti bassa:

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

Gli strumenti guest per VirtualBox, QEMU/SPICE e VMware sono già nell'immagine: sono loro a fornire il ridimensionamento dello schermo e gli appunti condivisi.

Scorciatoie da tastiera

La tabella completa è nella pagina Caratteristiche. Quelle da imparare il primo giorno:

La tabella completa

Risolvere i problemi

• Lo schermo resta nero dopo il menu di avvio

  Scegli la voce con la grafica sicura (safe graphics). Se si avvia, installa da lì e poi attiva il driver proprietario dalla pagina Driver.

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

  Una macchina VirtualBox con 16 MB di memoria video. Portala a 128 MB e attiva l'accelerazione 3D; vedi Macchine virtuali qui sopra.

• Il desktop sembra lento

  Controlla il renderer OpenGL in Impostazioni → Informazioni. Con il rendering software le animazioni vengono disattivate da sole all'accesso; Tweaks → Prestazioni le disattiva a mano.

• La chiavetta si avvia ma poi si blocca in modi strani

  Esegui Check this medium for defects dal menu di avvio e verifica il checksum SHA-256 del download.

• Il Wi-Fi non funziona

  Apri la pagina Driver: il driver Broadcom è incluso nell'immagine. Per le altre schede, il menu di rete elenca ciò che il kernel ha riconosciuto.

• Il lettore di impronte non viene riconosciuto

  Apri Impronta digitale. Indica il produttore del sensore, dice se è un sensore nativo, “match on chip” o con binario del produttore, e spiega che cosa si può fare.

• Leggere i registri

  Che cosa è andato storto all'avvio, il registro del gestore degli accessi, quello del primo avvio e il nome del tema di avvio attivo:

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

Per una segnalazione, Informazioni → Copia rapporto mette la release e l'hardware negli appunti, e moonlight-selftest stampa che cosa sta facendo davvero il desktop.

moonlight-selftest | less

Compilarlo da soli

Tutta la distribuzione è un unico repository: la grafica deriva da un solo logo di partenza, i temi vengono generati da una sola tavolozza e un unico script trasforma tutto in una ISO avviabile che funziona con Secure Boot. Servono Docker (su qualsiasi sistema operativo, perché la build gira in un container) e circa 25 GB di spazio libero.

La ISO viene scritta in out/, con il checksum SHA-256 accanto. Su Windows, lancia lo script da Git Bash oppure usa build.ps1.

Com'è organizzata la build

Prima di creare la ISO, la build esegue più di 120 controlli obbligatori dentro l'immagine: il kernel, lo shim firmato, entrambi i temi, ogni MoonTool, i codec, i driver Wi-Fi, le traduzioni, e che lo sblocco con il volto e la password di emergenza siano disattivati. Se un controllo fallisce, la build si ferma. Lo spazio di lavoro è un volume Docker e non un bind mount, perché la proprietà dei file, i link simbolici e i nodi di dispositivo non sopravvivono a un bind mount su Windows o macOS.

Personalizzare

• L'identità della release

  config/moonlight.conf contiene ogni stringa che definisce la distribuzione.

• Grafica

  Sostituisci il logo di partenza o uno sfondo, rilancia tools/gen-branding.py, e animazione di avvio, GRUB, schermata di accesso, icone e grafica dell'installatore vengono rigenerati tutti.

• Colori

  tools/gen-themes.py contiene una tavolozza scura e una chiara e genera entrambi i temi completi con le stesse regole.

• Pacchetti installati

  packages/*.list, un pacchetto per riga, installati in ordine di nome di file; 99-purge.list elenca ciò che viene rimosso alla fine.

• Impostazioni predefinite del desktop

  rootfs/etc/dconf/db/moonlight.d/, in formato keyfile di dconf. Sono impostazioni predefinite, non blocchi: l'utente può cambiarle tutte.

• Ricompilare in fretta

  Dopo una modifica a rootfs/ o alle liste dei pacchetti, build.sh rootfs ripete la fase del chroot sulla base già in cache e build.sh image reimpacchetta la ISO; build.sh finish serve quando lavori sul menu di avvio.

Assistenza e segnalazione dei problemi

Una segnalazione utile dice che cosa ti aspettavi, che cosa è successo invece e su quale computer. MoonLightOS rende facile la terza parte:

• Informazioni su MoonLightOS → Copia rapporto mette negli appunti, come testo, la release, l'hardware, il renderer grafico e lo stato di Secure Boot.
• moonlight-selftest stampa le impostazioni del tema in uso, se il foglio di stile della shell è stato caricato correttamente, quale driver grafico è attivo e quali servizi non sono partiti.
• Per un problema all'avvio, la voce Verbose boot scrive ogni messaggio sullo schermo e sulla prima porta seriale.
• Per l'installatore, /var/log/moonlight-firstboot.log sul sistema installato e journalctl -b -p warning.

Dove inviarla

Un tracker pubblico dei problemi e un canale di assistenza verranno annunciati qui. Nel frattempo conserva la segnalazione: tutto ciò che deve contenere viene dai due strumenti qui sopra.