3.7 Install, Appendix: reorganized the presentation to put more options in the main text

This commit is contained in:
John McQuah 2022-08-11 15:08:11 -04:00
parent 071d30578c
commit d2ad588835
2 changed files with 104 additions and 152 deletions

View File

@ -44,117 +44,6 @@ menuentry "MemTest86+ 4.20" {
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
@ -224,12 +113,6 @@ EFI system partition. The two most common ways to shorten what looks like an
overly-verbose path to the kernel 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

View File

@ -213,14 +213,24 @@ kernel. For example:
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->The setup program installs a configuration file
%fn%/usr/src/linux-5.15.x/.config%% which is a good starting point for a
%fn%/usr/src/linux-5.15.55/.config%% which is a good starting point for a
custom kernel, because all needed options, like CONFIG_DEVTMPFS, are
enabled.
$ cd /usr/src/linux-5.15.x
$ cd /usr/src/linux-5.15.55
$ make menuconfig
$ make all
$ make modules_install
$ cp arch/x86/boot/bzImage /boot/vmlinuz-5.15.55-1
$ cp System.map /boot
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->The location %fn%/boot%% is the default path that GRUB will
search for kernel images. If you use SYSLINUX or the kernel itself as
your bootloader, then modify the @@cp@@ commands to copy the kernel into a
more appropriate location, e.g., the subdirectory %fn%EFI/BOOT%% under the
mountpoint of the EFI system partition.
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
@ -232,47 +242,106 @@ this file, %fn%config-5.15.55-modular%%, under %fn%/crux/kernel/contrib%% on
the installation media.
[[#BootLoader-Setup]] !!! Installing a Bootloader
-->If you plan to use syslinux as your bootloader, skip ahead to
[[#syslinux-install | "syslinux installation notes"]] in the appendix of this
document. Otherwise, proceed with '''grub-install''' according to the
instructions below.
First place a copy of the newly-compiled kernel in a standard location,
named so that it will be detected by %fn%grub-mkconfig%%. For example,
%fn%grub-mkconfig%% will be able to recognize '''/boot/vmlinuz-5.x''' as
a valid kernel image, but '''NOT''' a file named '''/boot/linuxkernel-5.x'''.
-->Unless you compiled your kernel to provide an EFI stub '''and have UEFI
boot mode enabled in your BIOS''', you will want to install a bootloader on
your hard disk. Simple instructions are provided below for four distinct
combinations of bootloader and BIOS setting. You are advised to choose one
of the following options based on how your BIOS is configured and on how
important you consider hand-editable configuration files. The EFI stub
option is presented in the [[#EFI-stub-install|Appendix]], if you find it
simpler to modify EFI variables rather than configuration files.
[@
$ cp arch/x86/boot/bzImage /boot/vmlinuz-5.15.55-1
$ cp System.map /boot
$ grub-mkconfig > /boot/grub/grub.cfg
@]
grub-mkconfig's output can be altered by setting variables in a
* GRUB, in UEFI boot mode:
** Install grub2 into the EFI system partition using the command
'''grub-install /boot/efi'''.
** Replace '''/boot/efi''' with the location of the mounted ESP. If
'''efibootmgr''' was selected during the package selection phase, grub-install
will automatically create a boot entry and make it active.
** Run @@grub-mkconfig > /boot/grub/grub.cfg@@, or
[[#grubcfg-manually|create a config file by hand]].
* GRUB, in legacy (non-UEFI) boot mode:
** Install grub2 into the Master Boot Record using the command
'''grub-install /dev/sd??'''.
** Replace '''/dev/sd??''' with the actual node of the device whose Master Boot
Record you want to overwrite, eg., '''/dev/sda''' for the first SATA disk.
** Run @@grub-mkconfig > /boot/grub/grub.cfg@@, or
[[#grubcfg-manually|create a config file by hand]].
** @@grub-mkconfig@@'s output can be altered by setting variables in a
configuration file, '''/etc/default/grub'''. This file is NOT created by
default and is not required, but is useful for customizing the video
resolution and grub menu colors without crafting a '''grub.cfg''' by hand.
For more information, see the GRUB manual at
[[http://www.gnu.org/software/grub/manual/]].
* For legacy boot (not UEFI):
** Install grub2 into the Master Boot Record using the command
'''grub-install /dev/sd??'''.
-->Replace '''/dev/sd??''' with the actual node of the device whose Master Boot
Record you want to overwrite, eg., '''/dev/sda''' for the first SATA disk.
* For UEFI booting:
** Install grub2 into the ESP using the command '''grub-install /boot/efi'''.
-->Replace '''/boot/efi''' with the location of the mounted ESP. If
'''efibootmgr''' was selected during the package selection phase grub-install
will automatically create a boot entry and make it active.
** Check that the ESP now contains the grub bootloader, and that an entry
for the grub bootloader now appears in the EFI variables.
* SYSLINUX, in UEFI boot mode:
** Copy the bootloader code from %fn%/usr/share/syslinux%% to the mounted
EFI system partition, specifically the subdirectory %fn%EFI/BOOT%%, which
most UEFI implementations will search by default. (In this example the ESP
is assumed to be mounted at %fn%/boot/efi%%)
[@
$ ls /boot/efi/
$ efibootmgr
$ 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
$ cp /usr/share/syslinux/efi64/ldlinux.e64 .
$ cp /usr/share/syslinux/efi64/syslinux.efi BOOTX64.EFI
@]
** Saving a copy of %fn%syslinux.efi%% to the more generic name
%fn%BOOTX64.EFI%% helps avoid the extra step of customizing boot entries
with @@efibootmgr@@.
** 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).
** Proceed to [[#syslinux-cfg|write a syslinux configuration file]], keeping
in mind where you saved the kernel image.
* SYSLINUX, in legacy (non-UEFI) boot mode:
** Create a syslinux directory on a vfat or ext2/3/4-formatted partition,
and populate it with the kernel and bootloader. '''Assuming that %fn%/boot%% is
on a partition marked bootable''', you can do:
[@
$ mkdir /boot/syslinux
$ cd /boot/syslinux
$ cp /usr/share/syslinux/ldlinux.c32 .
$ cp /usr/src/linux-5.15.55/arch/x86/boot/bzImage ../vmlinuz-5.15.55
$ extlinux --install /boot/syslinux
@]
** Replacing %fn%/boot/syslinux%% in the above commands with
%fn%/boot/efi/EFI/BOOT%% will make it easy to toggle between legacy and UEFI
boot modes.
** Next, overwrite the contents of the master boot record (MBR) with the
binary blob appropriate for your partition type (%fn%gptmbr.bin%% in the
case of GPT/GUID partitioning, or %fn%mbr.bin%% in the case of DOS
partitioning).
[@
$ PTYPE=$(fdisk -l /dev/sda | grep "^Disklabel type" | cut -d " " -f3)
$ [ "$PTYPE" = "gpt" ] && BINBLOB=gptmbr.bin || BINBLOB=mbr.bin
$ dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/$BINBLOB of=/dev/sda
@]
** Proceed to write a syslinux configuration file, keeping in mind where you
saved the kernel image.
[[#syslinux-cfg]] Template for a SYSLINUX configuration file
If you select SYSLINUX as your bootloader, you need to tell it where
to find your kernel and the root filesystem.
SYSLINUX interprets relative paths to the kernel in reference to the
%fn%syslinux.cfg%% file. In the template below, suppose @@extlinux@@
assigned %fn%/boot/syslinux%% as the preferred location for
%fn%syslinux.cfg%%, and a copy of the kernel was saved in the parent
directory as %fn%/boot/vmlinuz-5.15.55%%. The relative path therefore
begins with %fn%../% .
[@
cat <<EOF > syslinux.cfg
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
EOF
@]
-->More information about UEFI and other boot loader/manager options can be
found in the CRUX wiki at [[https://crux.nu/Wiki/UEFI]].