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

[[#syslinux-install]]
!! 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 sufficient.

 $ 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 (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.

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

[[#syslinux-cfg]]
!!! 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, 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 details.

[[#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 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'

-> For maximum portability, you can also identify the root filesystem using its
partition UUID. Run @@ls -l /dev/disk/by-partuuid/@@ to discover the UUID of the
known partitions, and then modify the @@efibootmgr@@ arguments to use the
identifier of the root partition. '''Note: this option is more fragile than
specifying the root partition using its device node, because of the delay in
scanning all partitions to construct the list of their UUIDs. If you encounter
an error when booting your CRUX system this way, you will have to use the
installation media (or another rescue disk) to recreate the EFI boot entry with
device node instead, or with an additional boot option that gives the kernel more
time to enumerate the partitions.'''

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

* 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(\BOOT\vmlinuz-5.15.26.efi)72006f006f0074...
Boot0001* Linux 5.15.55	 HD(1,GPT,d5a44413-...,0x800,0x64000)/File(\BOOT\vmlinuz-5.15.55.efi)72006f006f0074...

$ efibootmgr -o 0001,0000
@]

[[#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
[[https://gitlab.com/SiFuh/Documentation/-/blob/master/CRUX-3.6-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.