The system installer for Sunlight Linux, a UEFI-only Linux distribution.
Written in Go as a port and adaptation of
clr-installer: the core
subsystems are reimplemented (not copied) and reduced to what Sunlight
installs, and it reads clr-installer's config format, so an existing
clr-installer config.yaml runs here. This is the same relationship
slinit has to dinit.
A full install runs end to end under UEFI: it partitions and formats the disk, lays down the base system, installs GRUB, and configures first boot.
Interim: Sunlight has no package repository of its own yet, so until it does slinstaller installs the base system from Void's official repo. That means a test install currently comes up with runit, not slinit — enough to prove the installer end to end; slinit takes over once it is in a repo we control.
The install runs as an ordered sequence; each step is its own package:
pre-install hooks → partition → mount → bind /proc,/sys,/dev
→ base system (xbps) → fstab → swap file → bootloader (GRUB-EFI)
→ first-boot config → network → save config → post-install hooks
| Area | What it does |
|---|---|
| Disk | GPT, an EFI System Partition, partitions by parted; mkfs.* / mkswap; the last partition can fill the disk |
| Encryption | LUKS on any partition typed crypt (cryptsetup, crypttab, rd.luks cmdline, initramfs rebuild) |
| Swap | a swap partition, or a swap file (swapFileSize) |
| Base system | xbps-install from a repository, with the signing keys and a chrooted reconfigure |
| Bootloader | GRUB for UEFI (grub-install + grub-mkconfig), kernel arguments from the config |
| Kernel settings | command-line profiles, console log level, CPU governor and P-State mode, kdump reservation — see Kernel settings |
| First boot | hostname, timezone, console keymap, locale, user accounts (with wheel sudo for admins and SSH keys) |
| Network | dhcpcd (DHCP by default; static interfaces become /etc/dhcpcd.conf stanzas) |
| Hooks | pre/post-install commands, chrooted or not, with $chrootDir/$chrooted |
With no config file it runs interactively: a full-screen wizard on a real
terminal, or a plain prompt flow over a serial console or a pipe (--text
forces the latter). Deliberately out of scope: BIOS/MBR, systemd, Clear Linux
specifics.
slinstaller runs as root from a live medium, against the machine's disk. It is destructive, so it defaults to a dry run and makes you confirm.
# Build
go build -o slinstaller ./cmd/slinstaller
# See the disks
./slinstaller --list-disks
# From a config file: print the plan (touches nothing), then carry it out
./slinstaller config.yaml
sudo ./slinstaller --apply config.yaml # retype the disk path to confirm
# Or interactively (no config file): pick a disk and answer a few questions
sudo ./slinstallerUseful flags: --repo/--keys/--arch/--packages for the base
install, --root for the target mount tree, and --through <stage> to run
only up to a stage (for VM testing). An encrypted layout takes its
passphrase from SLINSTALLER_LUKS_PASSPHRASE or a prompt — never from the
config.
⚠️ Partitioning, formatting and bootloader installs are irreversible. Try changes in a VM (QEMU + OVMF) against a scratch image — seedemo/vm, a reproducible harness that boots a live ISO and installs end to end. Never on a disk with data you care about.
The config is clr-installer's format. A minimal UEFI install:
targetMedia:
- name: sda
type: disk
children:
- { name: sda1, type: part, fstype: vfat, mountpoint: /boot, size: 512M }
- { name: sda2, type: part, fstype: swap, size: 2G }
- { name: sda3, type: part, fstype: ext4, mountpoint: / } # no size = fill
hostname: sunlight
keyboard: us
language: en_US.UTF-8
users:
- login: me
password: "$6$...crypt hash..." # never a plaintext password
admin: true # wheel + sudoMark a partition type: crypt to encrypt it. Validate reports every
problem at once before any disk is touched. See demo/uefi-basic.yaml
and doc/architecture.md.
These keys are slinstaller's own. All are optional, and a config that uses none of them is a plain clr-installer config.
targetMedia:
- type: disk
match: { serial: S5GXNX0T123456 } # or wwn, model, path: /dev/disk/by-id/...
wipe: discard # superblock (default), zero, random, discard
children:
- { type: part, fstype: vfat, mountpoint: /boot, size: 512M }
- { type: part, fstype: swap, size: auto, mount-options: discard }
- type: part
fstype: btrfs
mountpoint: /
mount-options: noatime,compress=zstd
subvolumes:
- { name: "@", mountpoint: / }
- { name: "@home", mountpoint: /home }
bootloader:
terminal: serial # the boot menu on the kernel's serial console too
removable: true # also install at EFI/BOOT/BOOTX64.EFI
update-nvram: true # false leaves the firmware's boot entries alone
probe-other-os: false # true lists other systems in the menu
httpProxy: http://proxy:3128
noProxy: localhost,10.0.0.0/8
power-state: poweroff # reboot, poweroff, halt or kexec when the install ends
write-files:
- { path: /etc/motd, content: "Welcome.\n", permissions: "0644" }matchnames the disk by what does not change between boots. Exactly one disk has to fit; none, or several, stops the install.size: auto(a swap partition or volume, orswapFileSize) is sized from the machine's memory, between 1 and 8 GiB.spare: trueon atype: raidpartition makes it a hot spare.wipeother thansuperblockgoes over the whole disk and takes as long as the disk is large.
Installing from an image. image: base.tar.zst (or --image) unpacks a
root filesystem image — a tar archive or a squashfs — instead of installing
packages. The image is the whole base system: kernel, GRUB and whatever the
layout needs to boot have to be in it.
Installing beside what is there. --discover /dev/sda prints the disk's
present layout as a config that keeps every partition; edit it to say where
the new system goes. An existing ext2/3/4, ntfs or btrfs partition can give up room for it:
reusePartitions: true
targetMedia:
- name: sda
type: disk
children:
- { name: sda1, type: part, fstype: vfat, mountpoint: /boot/efi, preserve: true }
- { name: sda2, type: part, fstype: ext4, preserve: true, resize: 40G } # shrunk, data kept
- { name: sda3, type: part, fstype: ext4, mountpoint: /, create: true } # in the room that leavesThe filesystem is shrunk first and the partition after it, and a create
partition with no start goes in the largest free region. Shrinking a
filesystem is not something to do without a backup.
Servers. A root on RAID is only redundant if the machine can still boot with a disk gone, so a second disk can carry a spare ESP; and an array can hold a volume group or an encrypted volume rather than a filesystem:
targetMedia:
- name: sda
type: disk
children:
- { name: sda1, type: part, fstype: vfat, mountpoint: /boot/efi, size: 512M }
- { name: sda2, type: raid, raid: md0 }
- name: sdb
type: disk
children:
- { name: sdb1, type: part, fstype: vfat, size: 512M, esp: true } # spare ESP
- { name: sdb2, type: raid, raid: md0 }
raid:
- name: md0
level: 1
encrypted: true # LUKS on the array (optional)
volumeGroup: vg0 # the array is the group's physical volume
children:
- { name: root, fstype: ext4, mountpoint: /, size: 40G }
- { name: var, fstype: xfs, mountpoint: /var }
networkInterfaces:
- name: bond0
bond: { members: [eth0, eth1], mode: 802.3ad }
- name: bond0.100
vlan: { id: 100, link: bond0 }
addrs: [{ ip: 10.0.100.2, netmask: 255.255.255.0 }]
gateway: 10.0.100.1
routes: [{ to: 10.1.0.0/16, via: 10.0.100.254 }]
report-url: https://deploy.example/events # progress, stage by stage, as JSONA spare ESP needs the main one at /boot/efi (at /boot the kernels would
live on one disk only). Several type: lvm partitions may share a
volumeGroup. Bonds, VLANs and bridges are created at each boot by a
service the installer writes; a bridge: { members: [...] } entry works the
same way.
A whole-disk image. disk-image: disk.raw.zst with a single disk in
targetMedia (no layout) writes the image over the disk and stops: the image
already is the partitioned, configured system.
More on the command line: the config may be an https:// URL; --resume
continues an install that failed installing the base system without
partitioning again, and --resume-from <stage> does so from any later
stage; --json-yaml old.json converts the JSON descriptor of
clr-installer's predecessor into a config; --unmount takes down what a --through run left
mounted and --in-target "cmd" runs a command inside it. A partition table
whose partitions are named CLR_BOOT, CLR_ROOT, CLR_SWAP,
CLR_MNT_/path (with _F to format) comes out of --discover already
saying what goes where.
Finer points, all optional:
| key | on | what it does |
|---|---|---|
crypt-options: discard |
an encrypted volume | extra crypttab options (the kernel command line, for the root) |
partition-type, partition-uuid, partition-name |
a partition | its entry in the GPT |
uuid |
a filesystem | its UUID (a volume id for vfat) |
passno, freq |
a filesystem | its fstab fsck pass and dump frequency |
metadata: "1.0" |
a raid entry |
the array's superblock format |
stage-hooks: { partition: [...] } |
the config | commands after a named stage |
install-type: server / desktop |
the config | a larger smallest root (4 GB / 20 GB) |
kernel-fallback: linux-lts |
the config | the kernel to try when the configured one cannot be installed |
power-state-delay: 30 |
the config | seconds before the machine reboots or powers off |
system-upgrade: true |
the config | the installed system brought up to date before the bootloader is set up |
kernel-remove: [linux6.18] |
the config | kernel packages removed once the base system is in |
partitions: [...] |
a raid entry |
a partition table on the array itself (/dev/md0p1, …) |
message-url |
the config | where installer messages are looked for and shown |
power-state: kexec loads the installed kernel and starts it directly,
without going back through the firmware.
image and disk-image may be https:// URLs: the image is unpacked or
written as it downloads, so it only has to fit on the target. resize also
works on btrfs, and Safe Installation in the full-screen installer offers to
shrink a partition when the disk has no unallocated space. --log-level 2
keeps the terminal to the stages and the result.
On the command line, --system-check config.yaml runs every pre-install
check and stops without changing anything. A failed install leaves a
diagnostics archive in /tmp (--diagnostics names it): the error, the log,
the disks, and the config without its password hashes. Only one --apply
runs at a time.
The wizard's kernel sections all end up as ordinary config, so a saved config replays them:
kernel-profile: Server # which profile the arguments came from
kernel-arguments:
add:
- mitigations=auto
- transparent_hugepage=madvise
- cpufreq.default_governor=schedutil
- console=ttyS0,115200 # mirrored from the live system
console-log-level: 3 # 0 (emergency) to 7 (debug)| Key / section | What it does |
|---|---|
kernel-arguments |
add goes on the GRUB command line; remove is left out of it |
kernel-profile |
names the Kernel Command Line profile used (Server by default). The install recomputes what the profile derives from the hardware — see below |
console-log-level |
sets loglevel=N on the command line and kernel.printk = N 4 1 7 in /etc/sysctl.d/10-printk.conf; overrides a loglevel= among the arguments |
| Kernel Command Line | a profile picker (Server, Desktop, Realtime, Telco/RAN, virtualization, GPU, …) or Custom arguments; Details shows what a profile adds |
| CPU Frequency Governor | cpufreq.default_governor=; only the governors the chosen driver mode has are offered |
| AMD / Intel P-State Driver | amd_pstate= / intel_pstate= for the isolation profiles; shown only on the matching CPU |
| Crash Dump (kdump) | crashkernel= and panic=. Reserves the memory only — see the limit below |
kernel-profile and console-log-level are Sunlight extensions to
clr-installer's format; both are optional and a clr-installer config without
them is unaffected.
Three things to know:
-
Arguments are adapted to the machine the wizard runs on. IOMMU and nested-KVM arguments are written for the detected CPU vendor, and the Realtime and Telco/RAN profiles compute
isolcpus=,nohz_full=,rcu_nocbs=,irqaffinity=and the 1 GiB hugepage count from that machine's CPUs, NUMA nodes and RAM, and the saved config holds the result. Those values belong to the hardware, so whenkernel-profilenames a profile,--applyrecomputes them for the machine it runs on and reports what changed: the vendor arguments for any profile (intel_iommu↔amd_iommu,kvm-intel↔kvm-amd, and the P-State mode where the other vendor has the same one), and the CPU lists and hugepages for the isolating profiles. Every other argument is installed as written, so a saved config moves between machines, and between Intel and AMD. A config withkernel-profile: Custom(or none) is never rewritten — there--applyonly refuses, before touching the disk, a CPU list naming CPUs the machine lacks or hugepages that would leave it under 1 GiB.Two things the install does not put right, left to services on the installed system:
intel_idle.max_cstate, dropped when a config goes to AMD, is not restored if it later returns to Intel; and a governor chosen for a P-State mode the other vendor lacks is kept as written. -
The profiles run on the stock kernel. They rely on dynamic preemption (
preempt=full),nohz_fulland RCU callback offloading, which the packagedlinuxkernel has. That is low-latency tuning, not aPREEMPT_RTkernel. -
kdump is not complete yet.
crashkernel=reserves the memory, but nothing on the installed system loads a crash kernel into it or saves the dump: that needskexec-tools,makedumpfileand a boot service, which the installer does not set up.
slinstaller is one of the projects in the Sunlight Linux tree, wired up via slmanifests:
repo init -u https://github.com/sunlightlinux/slmanifests.git -b main
repo sync -j4
# slinstaller lands at src/installer/- doc/architecture.md — the config, the boundary, the port
- doc/port-status.md — what is ported from clr-installer, what is left
- CHANGELOG.md · STABILITY.md — what changed, what is stable
- CONTRIBUTING.md · SECURITY.md · CODE_OF_CONDUCT.md
- CLAUDE.md / EXAMPLES.md — guidelines for LLM-assisted work