diff --git a/crux-wiki/Handbook3-7-Appendix b/crux-wiki/Handbook3-7-Appendix index 8740564..d981984 100644 --- a/crux-wiki/Handbook3-7-Appendix +++ b/crux-wiki/Handbook3-7-Appendix @@ -1,15 +1,21 @@ ! 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. +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. +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: +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 @@ -41,18 +47,22 @@ 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. +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! +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. +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 @@ -61,33 +71,44 @@ sufficient. $ 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. +-> 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. +-> 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. +-> 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. +!!! 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.''' +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 @@ -98,19 +119,22 @@ binary blob into the master boot record. '''Remember to replace ''sda'' with you $ 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 +-> 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. +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 @@ -123,33 +147,48 @@ label CRUX-3.7 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. +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, 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. +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. --> 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. +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. -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. +-> 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. -* 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%%. +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 @@ -161,8 +200,18 @@ $ cp /usr/src/linux-5.15.55/arch/x86/boot/bzImage vmlinuz-5.15.55.efi $ 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. +* For maximum portability, you can also identify the root filesystem using its +partition UUID. Run @@ls /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.''' + + $ 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. [@ $ efibootmgr @@ -178,22 +227,30 @@ $ 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 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. +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 -[[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 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. +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 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.