263 lines
12 KiB
Plaintext
263 lines
12 KiB
Plaintext
! 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 -- 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
|
|
$ cd $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.
|
|
|
|
[[#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, since
|
|
@@extlinux@@ assigned %fn%/boot/efi/EFI/BOOT/%% as the preferred location for
|
|
%fn%syslinux.cfg%%, we copied the kernel to
|
|
%fn%/boot/efi/EFI/BOOT/vmlinuz-5.15.55%%.
|
|
|
|
!!! 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-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 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.
|
|
|
|
[[#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
|
|
[[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.
|