Skip to content

About

System installer for Sunlight Linux (UEFI-only). Beta stopgap: void-installer fork; long-term target: a Go rewrite modeled on clr-installer.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

slinstaller

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.

What it installs

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.

Using it

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 ./slinstaller

Useful 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 — see demo/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

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 + sudo

Mark 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.

Beyond clr-installer's format

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" }
  • match names 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, or swapFileSize) is sized from the machine's memory, between 1 and 8 GiB.
  • spare: true on a type: raid partition makes it a hot spare.
  • wipe other than superblock goes 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 leaves

The 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 JSON

A 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.

Kernel settings

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 when kernel-profile names a profile, --apply recomputes 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 with kernel-profile: Custom (or none) is never rewritten — there --apply only 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_full and RCU callback offloading, which the packaged linux kernel has. That is low-latency tuning, not a PREEMPT_RT kernel.

  • 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 needs kexec-tools, makedumpfile and a boot service, which the installer does not set up.

Where this fits

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/

Documentation

License

Apache License 2.0.

About

System installer for Sunlight Linux (UEFI-only). Beta stopgap: void-installer fork; long-term target: a Go rewrite modeled on clr-installer.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages