Appendix: add a bullet point to discuss the boot parameter root=PARTUUID=...
This commit is contained in:
parent
e5f0edb074
commit
7a0e0f04b8
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue