Appendix: add a bullet point to discuss the boot parameter root=PARTUUID=...

2022-08-05 09:32:59 -04:00 · 2022-08-05 09:32:59 -04:00 · 7a0e0f04b8
parent e5f0edb074
commit 7a0e0f04b8
1 changed files with 135 additions and 78 deletions
--- 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
+Many common problems are answered in the FAQ document, so if you experience
-[[http://crux.nu/Main/Faq | CRUX FAQ]] contains answers to your questions already.
+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
+The venerable bootloader LILO has been dropped as of CRUX version 3.7; most
-GRUB instead. This section presents another option, the SYSLINUX bootloader.
+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
+If your motherboard supports the UEFI boot mode, then installation of syslinux
-EFI system partition (mounted at %fn%/boot/efi%% in the example commands below) and writing a configuration that tells
+is as simple as copying a few files to the EFI system partition (mounted at
-syslinux where to find your kernel. First confirm that EFI variables are visible to the currently-running kernel; if you run
+%fn%/boot/efi%% in the example commands below) and writing a configuration that
-@@efivar -l@@ and see a list of %fn%universally-unique-identifier-VariableName%%s, then the following commands should be
+tells syslinux where to find your kernel. First confirm that EFI variables are
-sufficient.
+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
+-> Observe that the EFI bootloader was given a generic name in the fourth line
-%fn%/boot/efi/BOOT%% using the original filename provided by the '''syslinux''' package, then it would have been
+above. If you had saved it in fn%/boot/efi/BOOT%% using the original filename
-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.
+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
+-> The fifth command puts a copy of the kernel (renamed to show version
-command starts the vi editor on a buffer that will be written to %fn%syslinux.cfg%%, which must contain a line giving the
+information) in the working directory. The final command starts the vi editor on
-path to the kernel image. See the [[#syslinux-cfg| "SYSLINUX configuration file template"]] for details.
+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
+!!! Installation -- Legacy (MBR) booting
-If your motherboard does not support UEFI boot mode (or if you disabled it deliberately), then installing syslinux will
+If your motherboard does not support UEFI boot mode (or if you disabled it
-require you to overwrite the master boot record (MBR). The '''syslinux''' package provides two different binary
+deliberately), then installing syslinux will require you to overwrite the master
-blobs that can occupy the designated MBR area of the hard disk. To determine which binary blob is appropriate, you will
+boot record (MBR). The '''syslinux''' package provides two different binary
-need to remember what kind of partition table you wrote when you initialized your disk for CRUX. The older DOS (MBR)
+blobs that can occupy the designated MBR area of the hard disk. To determine
-partition table is supported by %fn%/usr/share/syslinux/mbr.bin%%, while the newer GPT (GUID) partition table is supported
+which binary blob is appropriate, you will need to remember what kind of
-by %fn%/usr/share/syslinux/gptmbr.bin%%. You can run @@fdisk -l /dev/sda@@ (replacing ''sda'' with your actual device) to
+partition table you wrote when you initialized your disk for CRUX. The older DOS
-remind yourself what the existing partition table looks like. An identification of the exact partition type (DOS or GPT)
+(MBR) partition table is supported by %fn%/usr/share/syslinux/mbr.bin%%, while
-will appear next to ''Disklabel type:'' in the fdisk output.
+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
+Once you determine the binary blob that will work with your partition table, run
-binary blob into the master boot record. '''Remember to replace ''sda'' with your actual device.'''
+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
+-> The @@extlinux@@ command takes a ''directory of the mounted EFI system
-than a device node. Upstream documentation begins with an example of calling the @@syslinux@@ command with the
+partition'' as its argument, rather than a device node. Upstream documentation
-''device node'' as its argument, which assumes that the EFI system partition is not mounted. Because you're already
+begins with an example of calling the @@syslinux@@ command with the ''device
-creating files on this partition, we prefer the command that won't require you to unmount the partition before running it.
+node'' as its argument, which assumes that the EFI system partition is not
-The @@extlinux@@ command is also smart enough to set its argument (the ''install target'') as the directory to be searched
+mounted. Because you're already creating files on this partition, we demonstrate
-for configuration files, so you can proceed to launch the editor on %fn%syslinux.cfg%% (see the next section for a
+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
+Now that the SYSLINUX bootloader is successfully installed, you need to tell it
-filesystem.
+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
+When giving the location of a kernel image, relative paths are interpreted in
-the example above, where @@extlinux@@ assigned %fn%/boot/efi/BOOT/%% as the preferred location for %fn%syslinux.cfg%%, the
+reference to the %fn%syslinux.cfg%% file. In the example above, where
-kernel would have to be copied to %fn%/boot/efi/BOOT/vmlinuz-5.15.55%%. Saving kernels here (in the BOOT subdirectory of
+@@extlinux@@ assigned %fn%/boot/efi/BOOT/%% as the preferred location for
-the EFI system partition) is a common practice when using the kernel itself as a bootloader; see the next section for more
+%fn%syslinux.cfg%%, the kernel would have to be copied to
-details.
+%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
+GRUB and SYSLINUX offer the most familiar experience for users coming from LILO.
-BIOS and the Master Boot Record, all subsequent updates to the GRUB or SYSLINUX configuration only involve editing a
+After a one-time interaction with the BIOS and the Master Boot Record, all
-flat-text file, and the contents of the bootsector or the NVRAM never need to be revisited. But if you aren't intimidated
+subsequent updates to the GRUB or SYSLINUX configuration only involve editing a
-by the prospect of manipulating EFI variables directly, another option is to let the Linux kernel image provide the EFI
+flat-text file. Although with LILO you had to run @@/sbin/lilo@@ after editing
-bootloader code itself.
+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''.
+A third way to boot into your CRUX system involves direct interaction with the EFI
-Legacy MBR booting is not supported with this method.
+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
+-> Note: this type of booting only works in UEFI mode, and when your kernel has
-you to append options like ''root=/dev/sda2'' to the line that boots the kernel, but some buggy UEFI implementations do
+been built with ''CONFIG_EFI_STUB=y''. Legacy MBR booting is not supported with
-not honor such appended options. To be safe, you can customize the boot options during the kernel configuration process
+this method.
 (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
+As with GRUB and SYSLINUX, the kernel has to be told which device to use as a
-compatibility, save it with the extension %fn%.efi%%.
+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
+* For maximum portability, you can also identify the root filesystem using its
-assigned to the newly-created entry, and then use that number to specify the desired boot order.
+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
+A common scenario that prevents the usual practice of booting a slimmed-down
-root filesystem (and then loading modules to initialize other hardware) is that the root filesystem is not a physical
+kernel containing only the drivers for the root filesystem (and then loading
-volume, but rather a logical volume inside an encryption layer like LUKS. To handle this situation, you will need to go
+modules to initialize other hardware) is that the root filesystem is not a
-beyond the kernel building process outlined above, and also create a compressed filesystem image (called an ''initramfs'')
+physical volume, but rather a logical volume inside an encryption layer like
-that contains the lvm and cryptsetup packages (and the drivers for usb input devices, if you chose not to compile them
+LUKS. To handle this situation, you will need to go beyond the kernel building
-into the kernel). Creating such an initramfs was once an intricate procedure, but tools like '''dracut''' make it much
+process outlined above, and also create a compressed filesystem image (called an
-simpler these days.
+''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
+If running @@dracut@@, and saving the initramfs alongside the kernel in the EFI
-deviations from the usual CRUX installation procedure, then one section of the appendix would suffice to explain how to do
+system partition, had been the only deviations from the usual CRUX installation
-full-disk encryption in CRUX. But preparation for this setup begins at the partitioning stage, when you need to call
+procedure, then one section of the appendix would suffice to explain how to do
-commands from the '''lvm2''' and '''cryptsetup''' packages before creating and mounting your filesystems. So this section
+full-disk encryption in CRUX. But preparation for this setup begins at the
-of the appendix just points to a separate document, where an
+partitioning stage, when you need to call commands from the '''lvm2''' and
-[[https://gitlab.com/SiFuh/Documentation/-/blob/master/CRUX-3.6-Encrypted.txt | outline for installing CRUX with full-disk
+'''cryptsetup''' packages before creating and mounting your filesystems. So this
-encryption]] is given from beginning to end. Even if full-disk encryption is not your desired endpoint and you just want
+section of the appendix just points to a separate document, where an
-to learn more about highly-modular kernel configs, the creation of an initramfs is best viewed in the context of the
+[[https://gitlab.com/SiFuh/Documentation/-/blob/master/CRUX-3.6-Encrypted.txt | outline for installing CRUX with full-disk encryption]]
-overall installation procedure, after having successfully built some less-modular kernels yourself. Studying the upstream
+is given from beginning to end. Even if full-disk encryption is not your desired
-documentation for any unfamiliar command in the linked outline (eg., %fn%cryptsetup%%, %fn%pvcreate%%, or %fn%dracut%%)
+endpoint and you just want to learn more about highly-modular kernel configs,
-is an excellent way to distinguish the functions performed by the various components.
+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.