263 lines
12 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]]
!! 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 -- Legacy (MBR) 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.
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. The first command sets
''INSTALLDIR'' as the path to a directory on a vfat or ext2/3/4 filesystem
('''which must be flagged as bootable in the partition table'''). In this
example we use a path that minimizes the hassle when toggling your BIOS between
UEFI and legacy boot methods. A less confusing option is commented out, for
BIOSes that truly have no UEFI capability.'''
$ INSTALLDIR=/boot/efi/EFI/BOOT # or /boot/syslinux
$ PTYPE=$(fdisk -l /dev/sda | grep "^Disklabel type" | cut -d " " -f3)
$ [ "$PTYPE" = "gpt" ] && BINBLOB=gptmbr.bin || BINBLOB=mbr.bin
$ mkdir -p $INSTALLDIR
$ cp /usr/share/syslinux/ldlinux.c32 .
$ cp /usr/src/linux-5.15.55/arch/x86/boot/bzImage vmlinuz-5.15.55
$ extlinux --install $INSTALLDIR
$ dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/$BINBLOB of=/dev/sda
$ vi syslinux.cfg
-> The @@extlinux@@ command takes a ''directory under a mounted 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 partition is not mounted. Because you're
already creating files on this partition, we demonstrate 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 filesystem.
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, since
@@extlinux@@ assigned %fn%/boot/efi/EFI/BOOT/%% as the preferred location for
%fn%syslinux.cfg%%, we copied the kernel to
!!! 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 sufficient.
$ mkdir -p /boot/efi/EFI/BOOT
$ cd /boot/efi/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.
* Most UEFI implementations search the subdirectory %fn%EFI/BOOT%% of the
EFI partition for the bootloader, defaulting to a file named
%fn%BOOTX64.EFI%% in that subdirectory.
** If you choose a different mountpoint for the EFI partition, adjust the @@mkdir@@ and @@cd@@ commands accordingly (UEFI itself is completely agnostic about mountpoints specified in %fn%/etc/fstab).
** Copying the %fn%syslinux.efi%% file with its original name
would require you to run @@efibootmgr@@ and 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.
!! 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 image 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).
-> The flexibility afforded by all these options can be overwhelming (but
considerably less so than the decisions involved in full-disk encryption;
see the next section). Each presentation above (SYSLINUX legacy, SYSLINUX
UEFI, and EFI STUB) is meant to illustrate just one possible way of setting
up a bootloader, and you're welcome to explore variations on these
instructions to suit your preferred partitioning scheme.
!! 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.