200 lines
11 KiB

! Appendix
!! Troubleshooting
Many common problems are answered in the FAQ document, so if you experience problems please check whether the
[[ | 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.
!! 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 [[]]. 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'''.
!! SYSLINUX installation notes
The venerable bootloader LILO has been dropped as of CRUX version 3.7; most users will find it straightforward to adopt
GRUB instead. This section presents another option, the SYSLINUX bootloader.
!!! Precaution
Installing a new boot manager is like modifying the partition table using fdisk or installing a new system kernel. Please create a rescue boot disk first!
!!! Installation -- UEFI booting
If your motherboard supports the UEFI boot mode, then installation of syslinux is as simple as copying a few files to the
EFI system partition (mounted at %fn%/boot/efi%% in the example commands below) and writing a configuration that tells
syslinux where to find your kernel. First confirm that EFI variables are visible to the currently-running kernel; if you run
@@efivar -l@@ and see a list of %fn%universally-unique-identifier-VariableName%%s, then the following commands should be
$ mkdir -p /boot/efi/BOOT
$ cd /boot/efi/BOOT
$ cp /usr/share/syslinux/efi64/ldlinux.e64 .
$ cp /usr/share/syslinux/efi64/syslinux.efi BOOTX64.EFI
$ cp /usr/src/linux-5.15.55/arch/x86/boot/bzImage vmlinuz-5.15.55
$ vi syslinux.cfg
-> Remember to change %fn%/boot/efi%% to the actual mount point of your EFI system partition.
-> Observe that the EFI bootloader was given a generic name in the fourth line above. If you had saved it in
%fn%/boot/efi/BOOT%% using the original filename provided by the '''syslinux''' package, then it would have been
necessary to run @@efibootmgr@@ to inform the BIOS about this new bootloader-like object. See [[#EFI-stub-install | "EFI Stub installation"]] for an example of using @@efibootmgr@@ to create new boot entries.
-> The fifth command puts a copy of the kernel (renamed to show version information) in the working directory. The final
command starts the vi editor on a buffer that will be written to %fn%syslinux.cfg%%, which must contain a line giving the
path to the kernel image. See the [[#syslinux-cfg| "SYSLINUX configuration file template"]] for details.
!!! Installation -- Legacy (BIOS) booting
If your motherboard does not support UEFI boot mode (or if you disabled it deliberately), then installing syslinux will
require you to overwrite the master boot record (MBR). The '''syslinux''' package provides two different binary
blobs that can occupy the designated MBR area of the hard disk. To determine which binary blob is appropriate, you will
need to remember what kind of partition table you wrote when you initialized your disk for CRUX. The older DOS (MBR)
partition table is supported by %fn%/usr/share/syslinux/mbr.bin%%, while the newer GPT (GUID) partition table is supported
by %fn%/usr/share/syslinux/gptmbr.bin%%. You can run @@fdisk -l /dev/sda@@ (replacing ''sda'' with your actual device) to
remind yourself what the existing partition table looks like. An identification of the exact partition type (DOS or GPT)
will appear next to ''Disklabel type:'' in the fdisk output.
-> Also inspect the @@fdisk -l@@ output to make sure that the boot flag is
enabled on the partition where you save %fn%ldlinux.c32%% in the commands
below. This partition must be flagged as bootable in order for the binary
blob to proceed with loading the syslinux code.
Once you determine the binary blob that will work with your partition table, run the commands that will copy that
binary blob into the master boot record. '''Remember to replace ''sda'' with your actual device.'''
$ PTYPE=$(fdisk -l /dev/sda | grep "^Disklabel type" | cut -d " " -f3)
$ [ "$PTYPE" = "gpt" ] && BINBLOB=gptmbr.bin || BINBLOB=mbr.bin
$ mkdir -p /boot/efi/BOOT
$ cd /boot/efi/BOOT
$ cp /usr/share/syslinux/ldlinux.c32 .
$ extlinux --install /boot/efi/BOOT/
$ dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/$BINBLOB of=/dev/sda
$ vi syslinux.cfg
-> The @@extlinux@@ command takes a ''directory of the mounted EFI system partition'' as its argument, rather
than a device node. Upstream documentation begins with an example of calling the @@syslinux@@ command with the
''device node'' as its argument, which assumes that the EFI system partition is not mounted. Because you're already
creating files on this partition, we prefer the command that won't require you to unmount the partition before running it.
The @@extlinux@@ command is also smart enough to set its argument (the ''install target'') as the directory to be searched
for configuration files, so you can proceed to launch the editor on %fn%syslinux.cfg%% (see the next section for a
template) without changing directory.
!!! Template for a SYSLINUX configuration file
Now that the SYSLINUX bootloader is successfully installed, you need to tell it where to find your kernel and the root
default CRUX-3.7
prompt 1
timeout 10
label CRUX-3.7
say "Now booting into CRUX"
kernel vmlinuz-5.15.55
append root=/dev/sda2 rw quiet
When giving the location of a kernel image, relative paths are interpreted in reference to the %fn%syslinux.cfg%% file. In
the example above, where @@extlinux@@ assigned %fn%/boot/efi/BOOT/%% as the preferred location for %fn%syslinux.cfg%%, the
kernel would have to be copied to %fn%/boot/efi/BOOT/vmlinuz-5.15.55%%. Saving kernels here (in the BOOT subdirectory of
the EFI system partition) is a common practice when using the kernel itself as a bootloader; see the next section for more
!! 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, and the contents of the bootsector or the NVRAM never need to be revisited. But if you aren't intimidated
by the prospect of manipulating EFI variables directly, another option is to let the Linux kernel image provide the EFI
bootloader code itself.
-> 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 the BOOT 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/BOOT
$ cd /boot/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 '\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.
$ efibootmgr
BootCurrent: 0000
Timeout: 1 seconds
BootOrder: 0000,0001
Boot0000* Linux 5.15.26 HD(1,GPT,d5a44413-5bea-b24c-b4b7-76b32d5d2ed4,0x800,0x64000)/File(\BOOT\vmlinuz-5.15.26.efi)72006f006f0074...
Boot0001* Linux 5.15.55 HD(1,GPT,d5a44413-5bea-b24c-b4b7-76b32d5d2ed4,0x800,0x64000)/File(\BOOT\vmlinuz-5.15.55.efi)72006f006f0074...
$ efibootmgr -o 0001,0000
!! 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 lvm 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
[[ | 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 creation of an initramfs is best viewed in the context of the
overall installation procedure, after having successfully built some less-modular kernels yourself. 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.