diff --git a/crux-wiki/Handbook3-7-Appendix b/crux-wiki/Handbook3-7-Appendix index ca7c93b..5eee3c8 100644 --- a/crux-wiki/Handbook3-7-Appendix +++ b/crux-wiki/Handbook3-7-Appendix @@ -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 diff --git a/crux-wiki/Handbook3-7-Install b/crux-wiki/Handbook3-7-Install index b6c7f6f..dc3b62b 100644 --- a/crux-wiki/Handbook3-7-Install +++ b/crux-wiki/Handbook3-7-Install @@ -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,48 +242,107 @@ 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'''. -[@ -$ cp arch/x86/boot/bzImage /boot/vmlinuz-5.15.55-1 -$ cp System.map /boot -$ grub-mkconfig > /boot/grub/grub.cfg -@] +-->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. -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 < 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]].