path: root/limine-sync.8

.Dd October 17, 2026
.Dt LIMINE-SYNC 8
.Os
.Sh NAME
.Nm limine-sync
.Nd write the boot menu from what is in /boot
.Sh SYNOPSIS
.Nm
.Op Fl n
.Op Fl q
.Sh DESCRIPTION
.Nm
reconciles the EFI system partition with
.Pa /boot
and writes the Limine boot menu.
It takes no argument that changes what it does: the result is a
function of three directory listings.
.Bl -tag -width /lib/modules -offset indent
.It Pa /boot
what the packages staged: kernels, the initramfs, microcode.
.It Pa /lib/modules
the module trees, which decide whether a kernel is usable.
.It Pa /boot/efi
the current state of the ESP, which is made to match.
.El
.Pp
.Xr mkpkg 8
runs it through the
.Li boot/
trigger whenever a package adds or removes something there, so
installing or removing a kernel updates the menu by itself.
Running it by hand at any time is safe and changes nothing that is
already correct.
.Pp
A kernel in
.Pa /boot
is only offered if
.Pa /lib/modules/ Ns Ar version
exists: a kernel whose modules were removed, or whose install was
interrupted, would boot into a system that cannot load a single driver.
Such a kernel is reported and left out.
Every kernel, initramfs and microcode image on the ESP that no longer
has a counterpart in
.Pa /boot
is deleted.
Files
.Nm
did not put there are left alone.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl n
Dry run: print what would change and touch nothing.
Worth doing after editing the configuration.
.It Fl q
Quiet: do the work without printing what changed.
.El
.Sh THE MENU
The menu has two halves.
.Pa /etc/limine.conf.in
is written by hand and holds the global settings;
.Nm
replaces the line
.Li @KERNELS@
in it with an entry per usable kernel, newest first, and writes the
result to
.Pa /boot/efi/limine.conf .
That file is generated: edit the template, never it.
.Pp
.Li default_entry
must not appear in the template.
It is a one-based index, so it moves to a different kernel every time
one is added or removed;
.Nm
refuses a template that sets it.
To boot something other than the newest kernel, use
.Li remember_last_entry: yes ,
which follows the entry rather than its position.
.Pp
Each generated entry gets the command line from
.Li CMDLINE ,
and up to two
.Li module_path
lines: the microcode first, because the kernel only applies an early
update from the head of the initrd chain, then the initramfs.
.Sh CONFIGURATION
.Pa /etc/limine-sync.conf
supplies the few things a directory listing cannot: one
.Ar KEY Ns = Ns Ar value
per line, keys uppercase, surrounding quotes stripped, and
.Ql #
starting a comment anywhere on the line.
An unknown key is reported and ignored.
.Pa /etc/limine-sync.conf.example
documents every key at its default.
.Bl -tag -width MICROCODE
.It Li CMDLINE
The kernel command line, used verbatim for every entry.
.Sy Required, with no default .
The root device is the one setting that differs on every machine, and a
compiled-in guess would write a bootable-looking menu pointing at the
wrong disk and report success.
.Xr setup-boot 8
writes this line on an install target.
.It Li TITLE
The menu label; entries read
.Dq Ar TITLE Ar version .
Default:
.Li rawnix .
.It Li INITRD
The initramfs in
.Pa /boot .
tinyrd carries no modules and takes the LUKS UUID from the command
line, so one image serves every kernel and the name has no version in
it.
Empty boots without one, which an encrypted root cannot do.
Default:
.Li tinyrd.img .
.It Li MICROCODE
The early microcode image in
.Pa /boot ,
emitted as the first
.Li module_path
and only if the file is on the ESP.
.Pp
Unset, the default,
.Nm
uses whichever of
.Pa amd-ucode.img
and
.Pa intel-ucode.img
is on the ESP: a machine has one CPU vendor and installs one microcode
package, so the file that is there is the answer.
Set, that name is used and its absence is reported, since an omitted
microcode line is otherwise invisible until the next boot applies no
early update.
.Li none
emits none at all.
.It Li XEN_KERNEL , XEN_CMDLINE , XEN_OPTIONS , XEN_UCODE
Only relevant when a
.Pa xen-*.efi
is on the ESP; the newest one always gets a chainload entry.
These additionally generate
.Pa /boot/efi/xen.cfg ,
which picks dom0's kernel.
.Li XEN_KERNEL
pins a series, not a version:
.Li 6.12
selects the newest 6.12.x that has a module tree.
Empty leaves
.Pa xen.cfg
alone.
.El
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa /etc/limine-sync.conf
Settings; required, for
.Li CMDLINE .
.It Pa /etc/limine-sync.conf.example
Every key, documented at its default.
.It Pa /etc/limine.conf.in
The hand-written half of the menu, with
.Li @KERNELS@ .
.It Pa /boot/efi/limine.conf
The generated menu.
.It Pa /boot/efi/EFI/BOOT/BOOTX64.EFI
Limine itself, copied from
.Pa /usr/share/limine/ .
.It Pa /boot/efi/limine-bios.sys
Limine's BIOS stage on a legacy-boot machine.
Copied there by hand, and never touched by
.Nm .
.El
.Sh EXIT STATUS
.Ex -std
It refuses to run, changing nothing, when
.Li CMDLINE
is missing, when
.Pa /boot/efi
is not a mount point, or when the template sets
.Li default_entry .
.Sh EXAMPLES
After editing the configuration, look before you leap:
.Bd -literal -offset indent
# limine-sync -n
# limine-sync
.Ed
.Pp
A machine with an encrypted root; the UUID is the LUKS partition's,
from
.Ic cryptsetup luksUUID ,
and the mapping name in
.Li root=
is the one tinyrd creates:
.Bd -literal -offset indent
CMDLINE=cryptroot=UUID=xxxxxxxx-... root=/dev/mapper/croot ro quiet
.Ed
.Sh SEE ALSO
.Xr bootloader 7 ,
.Xr rawnix 7 ,
.Xr mkpkg 8 ,
.Xr setup-boot 8 ,
.Xr tinyrd 8
.Sh AUTHORS
.An zorz Aq Mt zorz@rawnix.org
.Sh CAVEATS
.Nm
writes the UEFI half of the boot chain: it requires a FAT partition
mounted at
.Pa /boot/efi
and installs
.Pa BOOTX64.EFI .
.Pp
On a machine that boots legacy BIOS it still writes the menu and the
kernels, and the firmware reads
.Pa limine.conf
from the same partition, but the BIOS half is installed by hand:
.Ic limine bios-install
writes stage 1 to the disk and
.Pa limine-bios.sys
is copied onto the partition.
.Nm
removes neither, so the copy survives every later run; after upgrading
limine, redo both together.
See
.Xr rawnix 7 .