Documentation/crux-wiki/Handbook3-7-Appendix

! Appendix
!! Troubleshooting

Many common problems are answered in the FAQ document, so if you experience
problems please check whether the [[http://crux.nu/Main/Faq | CRUX FAQ]]
contains answers to your questions already.

If you have further questions, there's a dedicated mailing list for CRUX, and an
IRC channel. Actual information about these can be found on the [[Community]]
page.

[[#grubcfg-manually]]
!! Writing a grub config file by hand

If %fn%grub-mkconfig%% does not work (eg., because you saved the kernel image
under a non-standard name), a grub.cfg file can be created manually. For more
information see the GRUB manual at [[http://www.gnu.org/software/grub/manual/]].
A simple example configuration might look like the following:

[@
# Display the menu for 10 seconds
set timeout=10

# Boot the first entry by default
set default=0

# Boot entries follow

# Default CRUX boot entry
menuentry "CRUX 3.7" {
	linux (hd0,msdos2)/boot/vmlinuz-5.15.55 root=/dev/sda2 quiet
}

# Single-user recovery entry
menuentry "CRUX 3.7 single-user mode" {
	linux (hd0,msdos2)/boot/vmlinuz-5.15.55 root=/dev/sda2 quiet single
}

# Memory test entry
menuentry "MemTest86+ 4.20" {
	linux16 (hd0,msdos2)/boot/memtest86+-4.20.bin
}
@]

Save the manual configuration file as '''/boot/grub/grub.cfg'''.

[[#EFI-stub-install]]
!! EFI Stub installation notes

GRUB and SYSLINUX offer the most familiar experience for users coming from LILO.
After a one-time interaction with the BIOS and the Master Boot Record, all
subsequent updates to the GRUB or SYSLINUX configuration only involve editing a
flat-text file. Although with LILO you had to run @@/sbin/lilo@@ after editing
its flat-text config, for GRUB and SYSLINUX you never have to touch the contents
of the bootsector or the NVRAM after the initial installation; changes to their
flat-text config files are automatically detected.

A third way to boot into your CRUX system involves direct interaction with the EFI
variables, letting the Linux kernel image provide the required EFI bootloader
code. This option has a workflow that might remind you of running @@/sbin/lilo@@
after building and installing each new kernel.

-> Note: this type of booting only works in UEFI mode, and when your kernel has
been built with ''CONFIG_EFI_STUB=y''. Legacy MBR booting is not supported with
this method.

As with GRUB and SYSLINUX, the kernel has to be told which device to use as a
root filesystem. Most modern BIOSes allow you to append options like
''root=/dev/sda2'' to the line that boots the kernel, but some buggy UEFI
implementations do not honor such appended options. To be safe, you can
customize the boot options during the kernel configuration process (the
@@make menuconfig@@ step), at the expense of making it harder to put the disk in
an external enclosure and boot from USB (when you want to travel lightly). If
you leave the boot options empty during kernel configuration, and the BIOS does
not honor your appended options, you might have to boot from a rescue disk to
get back into your system and fix things.

* Copy your built kernel to a subdirectory of the EFI system partition
(mounted at %fn%/boot/efi%%). For maximum compatibility, save it with the
extension %fn%.efi%%.

[@
$ mkdir -p /boot/efi/EFI/BOOT
$ cd /boot/efi/EFI/BOOT
$ cp /usr/src/linux-5.15.55/arch/x86/boot/bzImage vmlinuz-5.15.55.efi
@]

* Next, create a boot entry telling the BIOS about the kernel image you just saved.

 $ efibootmgr -c -d /dev/sda -L 'Linux 5.15.55' -l '\EFI\BOOT\vmlinuz-5.15.55.efi' -u 'root=/dev/sda2'


* Finally, change the boot order so that the newly-created boot entry is the
first one tried. Start by finding the number assigned to the newly-created
entry, and then use that number to specify the desired boot order. EXAMPLE:

[@
$ efibootmgr
BootCurrent: 0000
Timeout: 1 seconds
BootOrder: 0000,0001
Boot0000* Linux 5.15.26	 HD(1,GPT,d5a44413-...,0x800,0x64000)/File(\EFI\BOOT\vmlinuz-5.15.26.efi)72006f006f0074...
Boot0001* Linux 5.15.55	 HD(1,GPT,d5a44413-...,0x800,0x64000)/File(\EFI\BOOT\vmlinuz-5.15.55.efi)72006f006f0074...

$ efibootmgr -o 0001,0000
@]

-> As in the UEFI installation of SYSLINUX, the subdirectory %fn%EFI/BOOT%%
of the EFI system partition is the default path where the BIOS expects to
find a bootloader. This location is more obvious in the @@efibootmgr@@
commands, since @@efibootmgr@@ is agnostic about the mountpoint of your
EFI system partition. The two most common ways to shorten what looks like an
overly-verbose path to the kernel are:
** mount your EFI system partition somewhere else (and adjust the @@mkdir@@ and @@cd@@ commands as needed).
** save your kernel closer to the root of the EFI system partition (and change the @@efibootmgr@@ invocation as needed).

[[#initramfs]]
!! Notes on Initramfs

A common scenario that prevents the usual practice of booting a slimmed-down
kernel containing only the drivers for the root filesystem (and then loading
modules to initialize other hardware) is that the root filesystem is not a
physical volume, but rather a logical volume inside an encryption layer like
LUKS. To handle this situation, you will need to go beyond the kernel building
process outlined above, and also create a compressed filesystem image (called an
''initramfs'') that contains the lvm2 and cryptsetup packages (and the drivers
for usb input devices, if you chose not to compile them into the kernel).
Creating such an initramfs was once an intricate procedure, but tools like
'''dracut''' make it much simpler these days.

If running @@dracut@@, and saving the initramfs alongside the kernel in the EFI
system partition, had been the only deviations from the usual CRUX installation
procedure, then one section of the appendix would suffice to explain how to do
full-disk encryption in CRUX. But preparation for this setup begins at the
partitioning stage, when you need to call commands from the '''lvm2''' and
'''cryptsetup''' packages before creating and mounting your filesystems. So this
section of the appendix just points to a separate document, where an
[[CRUX-3.7-Encrypted.txt | outline for installing CRUX with full-disk encryption]]
is given from beginning to end. Even if full-disk encryption is not your desired
endpoint and you just want to learn more about highly-modular kernel configs,
the need for an initramfs is easier to motivate by considering a specific use
case like full-disk encryption. Studying the upstream documentation for any
unfamiliar command in the linked outline (eg., %fn%cryptsetup%%, %fn%pvcreate%%,
or %fn%dracut%%) is an excellent way to distinguish the functions performed by
the various components.