Bootloaders: Difference between revisions

Latest revision as of 02:05, 29 August 2025

A bootloader is a computer program that is responsible for booting a computer. In the case where it also provides an interactive menu with multiple boot choices, then it's often called a boot manager. This page shows the basic steps that you need to perform if, for any reason, you want to switch bootloaders or to apply some manual configuration.

The following bootloaders are available in Alpine Linux:-

Syslinux is the default lightweight bootloader used in Alpine Linux.
rEFInd is an easy-to-use EFI boot menu that allows booting different operating systems.
GRUB is a standard Linux bootloader.
EFI Boot Stub allows for booting Linux directly from a motherboard supporting UEFI or from another bootloader.
UEFI Secure Boot uses systemd-efistub or stubbyboot-efistub.

A Unified Kernel Image (UKI) is additionally supported, available for UEFI only. It is a UEFI executable that can be useful in certain use cases, including secure boot, clouds and containers.

Syslinux

If you want to switch from another bootloader back to Syslinux, or if for some reason you want to install Syslinux manually, then the following steps are required.

Install the syslinux package:

# apk add syslinux

If you're using GPT partitions, then install the GPT MBR onto the drive that you want to install the bootloader on (in this case, /dev/sda):

# dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/gptmbr.bin of=/dev/sda

Or, if you're using DOS partitions, then install the DOS MBR instead:

# dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=/dev/sda

Next, install the required Syslinux binaries. Despite being called extlinux, Syslinux supports booting from FAT12/16/32, NTFS, ext2/3/4, btrfs, XFS and UFS/FFS filesystems.

# extlinux --install /boot

The configuration file is located in /boot/extlinux.conf.

Alpine Linux ships with a script, update-extlinux, that automatically (re)generates this file, for example, on updates to Syslinux. The settings for this script can be found in /etc/update-extlinux.conf, including the option to disable automatic overwriting of /boot/extlinux.conf.

You can also place additional menu entries in the /etc/update-extlinux.d/ directory e.g. for dual booting.

Using EFI with syslinux

The Alpine Linux installer automatically uses GRUB if EFI mode is detected. The section below is specifically about using EFI with Syslinux:

Assuming that /mnt is a FAT32 partition of type EF00 and that /boot belongs to the rootfs created after running setup-disk:

# mkdir -p /mnt/EFI/syslinux # cp /usr/share/syslinux/efi64/* /mnt/EFI/syslinux/ # cp /boot/extlinux.conf /mnt/EFI/syslinux/syslinux.cfg # cp /boot/vmlinuz* /mnt/EFI/syslinux/ # cp /boot/initramfs* /mnt/EFI/syslinux/

You may need to modify /mnt/EFI/syslinux/syslinux.cfg to change the paths to absolute paths (just add a / in front of the vmlinuz/initramfs entries), or copy the files to /mnt/EFI/syslinux instead (XXX: untested).

In the end, the /mnt/EFI/syslinux/syslinux.cfg file should look like this:

Contents of /mnt/EFI/syslinux/syslinux.cfg

...
DEFAULT menu.c32
PROMPT 0
MENU TITLE Alpine/Linux Boot Menu
MENU HIDDEN
MENU AUTOBOOT Alpine will be booted automatically in # seconds
TIMEOUT 10
LABEL lts
  MENU DEFAULT
  MENU LABEL Linux lts
  LINUX /vmlinuz-lts
  INITRD /initrd-lts
  APPEND root=/dev/sda3 modules=sd-load,usb-storage,ext4 quiet

Finally, add syslinux to the EFI boot menu. Assuming that /dev/sda is your hard drive —be careful to check first what is its path on your device and to adjust accordingly:

# apk add efibootmgr # efibootmgr -c -d /dev/sda -p 1 -l \\EFI\\syslinux\\syslinux.efi -L "ALPINE-SYSLINUX"

You can now verify that the boot entry has been added:

efibootmgr

BootCurrent: 0001
Timeout: 0 seconds
BootOrder: 0001,0000,0002,...
Boot001* ALPINE-SYSLINUX HD(1,GPT,xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)/FILE(\EFI\syslinux\syslinux.efi)

rEFInd

rEFInd provides a graphical boot menu for UEFI systems.

GRUB

To install GRUB in BIOS mode, (optionally) remove the Syslinux package and install the required GRUB packages:

# apk del syslinux # apk add grub grub-bios

For EFI, install GRUB's EFI package instead. Note that /boot has to be an EFI-compatible filesystem, such as FAT32.

# apk add grub-efi efibootmgr

Next, install the MBR and GRUB binaries to disk for BIOS mode:

# grub-install /dev/vda

For EFI mode:

# grub-install --target=x86_64-efi --efi-directory=/boot

Then, add this line to /etc/default/grub:

Contents of /etc/default/grub

# GRUB_CMDLINE_LINUX_DEFAULT="quiet rootfstype=ext4 modules=sd-mod,usb-storage,ext4"

GRUB ships with an automatic configuration generator, including some automatic detection of other operating systems installed on the device:

# grub-mkconfig -o /boot/grub/grub.cfg

This script can be configured via the /etc/default/grub file.

If the font in the GRUB boot screen appears too small, then change the GRUB font.

Consult gnu.org's online manual for a list of available grub-mkconfig configuration options.

EFI Boot Stub

To boot directly from your motherboard's UEFI boot menu, a boot entry needs to be created either with a UEFI shell or with efibootmgr.

efibootmgr

Install efibootmgr:

# apk add efibootmgr

Create a boot entry. It is recommended to do this in a script, as efibootmgr does not allow for editing entries.

Contents of add-bootentry

#!/bin/sh

params="root=/dev/sdXZ rootfstype=ext4 rw \
  initrd=\intel-ucode.img \
  initrd=\initramfs-lts"

efibootmgr --create --label "Alpine Linux" \
  --disk /dev/sdX --part Y \
  --loader /vmlinuz-lts \
  --unicode "${params}" \
  --verbose

Where /dev/sdXY contains the EFI partition and /dev/sdXZ contains the root partition. If you are using linux-edge, then replace lts with edge in the script.

Note: The kernel contains the exhaustive list of ways to specify the block device. For a more robust boot entry, it is recommended to use a persistent name such as the PARTUUID.

Optionally, set the newly-created entry as the default:

# efibootmgr -n XXXX

Where XXXX is the boot number of the new entry.

Note: The loader and initrd file arguments are relative to the EFI partition. In a default installation, Alpine Linux places these files in /boot/, while EFI is mounted to /boot/efi/. You can either update fstab to mount EFI at /boot/, or manually copy them to /boot/efi/.

Using a UKI

Unified Kernel Image (UKI) is supported in UEFI only. It is possible to boot directly into a UKI. A UKI is a single file that contains the initfs, kernel and cmdline.

The UEFI Secure Boot page contains the instructions for setting up an a UKI. While this is typically done in order to SecureBoot, it is perfectly feasible to skip enrolling the custom keys and to leave SecureBoot off.

Additionally, it is possible to install the UKI in the default fallback path used by most UEFI implementations. By installing the UKI into this path, the system will automatically boot into it if no other entries are defined. This can be automated as part of the kernel hook by adding the following to /etc/kernel-hooks.d/secureboot.conf :

Contents of /etc/kernel-hooks.d/secureboot.conf

# For the edge kernel, install the UKI into the default UEFI path.
if [ "$1" == "edge" ]; then
  output_dir="/efi/EFI/Boot/"
  output_name="bootx64.efi"
fi

Note: bootx64.efi is only correct for x86_64 systems. For other architectures, the exact name will vary.

@@ Line 1: / Line 1: @@
-A bootloader, is a computer program that is responsible for booting a computer. If it also provides an interactive menu with multiple boot choices then it's often called a boot manager. This page shows the basic steps you need to perform, if you for any reason want to switch bootloaders or apply some manual configuration.
+A ''bootloader'' is a computer program that is responsible for booting a computer. In the case where it also provides an interactive menu with multiple boot choices, then it's often called a ''boot manager''. This page shows the basic steps that you need to perform if, for any reason, you want to switch bootloaders or to apply some manual configuration.
-The following bootloaders are available in Alpine Linux.
+The following bootloaders are available in Alpine Linux:-
-* <code>[[#Syslinux|Syslinux]]</code> is the default light-weight bootloader used in Alpine.<br>
+* <code>[[#Syslinux|Syslinux]]</code> is the default lightweight bootloader used in Alpine Linux.<br>
-* <code>[[#rEFInd|rEFInd]]</code> is an easy to use EFI boot menu that allows booting different operating systems.<br>
+* <code>[[#rEFInd|rEFInd]]</code> is an easy-to-use ''EFI'' boot menu that allows booting different operating systems.<br>
-* <code>[[#GRUB|GRUB]]</code> is a standard linux boot loader.<br>
+* <code>[[#GRUB|GRUB]]</code> is a standard Linux bootloader.<br>
-* <code>[[#EFI_Boot_Stub|EFI Boot Stub]]</code> allows booting linux directly from a motherboard supporting UEFI or another bootloader.<br>
+* <code>[[#EFI_Boot_Stub|EFI Boot Stub]]</code> allows for booting Linux directly from a motherboard supporting ''UEFI'' or from another bootloader.<br>
 * [[UEFI Secure Boot]] uses {{pkg|systemd-efistub}} or {{pkg|stubbyboot-efistub}}.
-== rEFInd ==
+A [[#Using a UKI|Unified Kernel Image (UKI)]] is additionally supported, available  for UEFI only. It is a UEFI executable that can be useful in [https://uapi-group.org/specifications/specs/unified_kernel_image/ certain use cases], including secure boot, clouds and containers.
-{{Main|Refind}}
-[[rEFInd]] provides a graphical boot menu for [[UEFI]] systems.
 == Syslinux ==
-If you want to switch from another bootloader back to Syslinux, or if you for some reason want to install Syslinux manually, the following steps are required.
+If you want to switch from another bootloader back to ''Syslinux'', or if for some reason you want to install Syslinux manually, then the following steps are required.
 Install the {{pkg|syslinux}} package:
@@ Line 22: / Line 19: @@
 {{cmd|# apk add syslinux}}
-If you're using GPT partitions, install the GPT MBR onto the drive you want to install the bootloader on (in this case {{path|/dev/sda}}):
+If you're using GPT partitions, then install the ''GPT MBR'' onto the drive that you want to install the bootloader on (in this case, {{path|/dev/sda}}):
 {{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/gptmbr.bin of=/dev/sda</nowiki>}}
-Or if you're using DOS partitions, install the DOS MBR instead:
+Or, if you're using DOS partitions, then install the ''DOS MBR'' instead:
 {{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=/dev/sda</nowiki>}}
 <!-- See also: http://www.syslinux.org/wiki/index.php?title=Mbr -->
-Next install the required Syslinux binaries. Despite being called <code>extlinux</code>, Syslinux supports booting from FAT12/16/32, NTFS, ext2/3/4, [[Btrfs|btrfs]], XFS, and UFS/FFS filesystems.
+Next, install the required Syslinux binaries. Despite being called <code>extlinux</code>, Syslinux supports booting from FAT12/16/32, NTFS, ext2/3/4, [[Btrfs|btrfs]], XFS and UFS/FFS filesystems.
 {{cmd|# extlinux --install /boot}}
@@ Line 38: / Line 34: @@
 The configuration file is located in {{path|/boot/extlinux.conf}}.
-Alpine ships with a script <code>update-extlinux</code> which automatically (re)generates this file, for example on updates to Syslinux. The settings for this script can be found in {{path|/etc/update-extlinux.conf}}, including the option to disable automatic overwriting of {{path|/boot/extlinux.conf}}.
+Alpine Linux ships with a script, <code>update-extlinux</code>, that automatically (re)generates this file, for example, on updates to Syslinux. The settings for this script can be found in {{path|/etc/update-extlinux.conf}}, including the option to disable automatic overwriting of {{path|/boot/extlinux.conf}}.
-You can also place additional menu entries in the {{path|/etc/update-extlinux.d/}} directory, e.g. for dual booting.
+You can also place additional menu entries in the {{path|/etc/update-extlinux.d/}} directory e.g. for dual booting.
 === Using EFI with syslinux ===
-Alpine Linux installer automatically uses [[#GRUB|Grub]], if EFI mode is detected. The below section is specifically about using EFI with syslinux:
+The Alpine Linux installer automatically uses [[#GRUB|GRUB]] if EFI mode is detected. The section below is specifically about using EFI with Syslinux:
-Assuming {{path|/mnt}} is a FAT32 partition of type EF00 and {{path|/boot}} belongs to the rootfs created after running <code>setup-disk</code>:
+Assuming that {{path|/mnt}} is a FAT32 partition of type EF00 and that {{path|/boot}} belongs to the rootfs created after running <code>setup-disk</code>:
 {{cmd|<nowiki># mkdir -p /mnt/EFI/syslinux
@@ Line 55: / Line 51: @@
 </nowiki>}}
-You may need to modify {{path|/mnt/EFI/syslinux/syslinux.cfg}} to change the paths to absolute paths (just add a / in front of the vmlinuz/initramfs entries),
+You may need to modify {{path|/mnt/EFI/syslinux/syslinux.cfg}} to change the paths to absolute paths (just add a / in front of the vmlinuz/initramfs entries), or copy the files to {{path|/mnt/EFI/syslinux}} instead (XXX: untested).
-or copy the files to {{path|/mnt/EFI/syslinux}} instead (XXX: untested).
+In the end, the {{path|/mnt/EFI/syslinux/syslinux.cfg}} file should look like this:
-At the end, the file {{path|/mnt/EFI/syslinux/syslinux.cfg}} should look like this:
 {{cat|/mnt/EFI/syslinux/syslinux.cfg|<nowiki>...
 DEFAULT menu.c32
@@ Line 74: / Line 70: @@
 </nowiki>}}
-And finally, add syslinux to EFI boot menu (assuming {{path|/dev/sda}} is your hard drive)
+Finally, add <code>syslinux</code> to the EFI boot menu.  Assuming that {{path|/dev/sda}} is your hard drive —'''''be careful to check first what is its path on your device and to adjust accordingly''''':
 {{cmd|<nowiki># apk add efibootmgr
 # efibootmgr -c -d /dev/sda -p 1 -l \\EFI\\syslinux\\syslinux.efi -L "ALPINE-SYSLINUX"
 </nowiki>}}
-You can now verify that the boot entry has been added
+You can now verify that the boot entry has been added:
 '''efibootmgr'''
@@ Line 88: / Line 85: @@
 Boot001* ALPINE-SYSLINUX HD(1,GPT,xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)/FILE(\EFI\syslinux\syslinux.efi)
 </pre>
+== rEFInd ==
+{{Main|rEFInd}}
+[[rEFInd]] provides a graphical boot menu for [[UEFI]] systems.
 == GRUB ==
@@ Line 97: / Line 99: @@
 </nowiki>}}
-For EFI, install GRUB's EFI package instead. Note that {{path|/boot}} has to be an EFI compatible filesystem like FAT32.
+For EFI, install GRUB's EFI package instead. Note that {{path|/boot}} has to be an EFI-compatible filesystem, such as FAT32.
 {{cmd|# apk add grub-efi efibootmgr}}
-Next install the MBR and GRUB binaries to disk for BIOS mode:
+Next, install the MBR and GRUB binaries to disk for BIOS mode:
 {{cmd|# grub-install /dev/vda}}
@@ Line 109: / Line 111: @@
 {{cmd|<nowiki># grub-install --target=x86_64-efi --efi-directory=/boot</nowiki>}}
-then add this line to {{path|/etc/default/grub}}:
+Then, add this line to {{path|/etc/default/grub}}:
 {{cat|/etc/default/grub|<nowiki># GRUB_CMDLINE_LINUX_DEFAULT="quiet rootfstype=ext4 modules=sd-mod,usb-storage,ext4"</nowiki>}}
-GRUB ships with an automatic config generator, including some automatic detection of other operating systems installed on the device:
+GRUB ships with an automatic configuration generator, including some automatic detection of other operating systems installed on the device:
 {{cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}
@@ Line 118: / Line 121: @@
 This script can be configured via the {{path|/etc/default/grub}} file.
-If the font in the GRUB boot screen appears small, then [[Fonts#Changing_GRUB_font_and_font_size|change the grub font]] .
+If the font in the GRUB boot screen appears too small, then [[Fonts#Changing_GRUB_font_and_font_size|change the GRUB font]].
-See [https://www.gnu.org/software/grub/manual/html_node/Simple-configuration.html] for a list of available options.
+Consult [https://www.gnu.org/software/grub/manual/html_node/Simple-configuration.html gnu.org's online manual] for a list of available <code>grub-mkconfig</code> configuration options.
 == EFI Boot Stub ==
-To boot directly from your motherboard's UEFI boot menu, a boot entry needs
+To boot directly from your motherboard's UEFI boot menu, a boot entry needs to be created either with a UEFI shell or with ''efibootmgr''.
-to be created with either a UEFI shell or ''efibootmgr''.
 === efibootmgr ===
-Install efibootmgr:
+Install {{Pkg|efibootmgr}}:
 {{cmd|# apk add efibootmgr}}
-Create a boot entry. It's recommended to do this in a script, as efibootmgr
+Create a boot entry. It is recommended to do this in a script, as efibootmgr does not allow for editing entries.
-does not allow editing entries.
 {{cat|add-bootentry|<nowiki>#!/bin/sh
@@ Line 148: / Line 149: @@
 </nowiki>}}
-Where {{path|/dev/sdXY}} contains the EFI partition and {{path|/dev/sdXZ}} contains the root partition. If you are using {{Pkg|linux-edge}}, replace <code>lts</code> with <code>edge</code> in the script
+Where {{path|/dev/sdXY}} contains the EFI partition and {{path|/dev/sdXZ}} contains the root partition. If you are using {{Pkg|linux-edge}}, then replace <code>lts</code> with <code>edge</code> in the script.
-{{Note|
+{{Note| The kernel contains the [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/init/do_mounts.c#n254 exhaustive list] of ways to specify the block device. For a more robust boot entry, it is recommended to use a persistent name such as the PARTUUID.
-The kernel contains the [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/init/do_mounts.c#n254 exhaustive list] of ways to specify the block device. For a more robust boot entry, it is recommended to use a persistent name such as the PARTUUID.
 }}
-Optionally, set the newly created entry as the default:
+Optionally, set the newly-created entry as the default:
 {{cmd|# efibootmgr -n XXXX}}
@@ Line 160: / Line 160: @@
 Where <code>XXXX</code> is the boot number of the new entry.
-{{Note|
+{{Note| The loader and initrd file arguments are relative to the EFI partition. In a default installation, Alpine Linux places these files in {{path|/boot/}}, while EFI is mounted to {{path|/boot/efi/}}. You can either update <code>fstab</code> to mount EFI at {{path|/boot/}}, or manually copy them to {{path|/boot/efi/}}.                                                                                           }}
-The loader and initrd file arguments are relative to the EFI partition. In a default installation, alpine places these files in {{path|/boot/}}, while EFI is mounted to {{path|/boot/efi/}}. You can either update fstab to mount EFI at {{path|/boot/}}, or manually copy them to {{path|/boot/efi/}}.                                                                                           }}
 == Using a UKI  ==
-'''Unified Kernel Image''' (UKI) is supported in UEFI only. It is possible to boot directly into a UKI. A UKI is a single file which contains the initfs, kernel and cmdline.
+'''[https://github.com/uapi-group/specifications/blob/main/specs/unified_kernel_image.md#unified-kernel-image-uki Unified Kernel Image]''' (UKI) is supported in UEFI only. It is possible to boot directly into a UKI. A UKI is a single file that contains the initfs, kernel and cmdline.
-The page [[UEFI Secure Boot]] contains the instructions for setting an a UKI.  While this is typically done in order to SecureBoot, it is perfectly feasible to skip enrolling the custom keys and leave SecureBoot off.
+The [[UEFI Secure Boot]] page contains the instructions for setting up an a UKI.  While this is typically done in order to ''SecureBoot'', it is perfectly feasible to skip enrolling the custom keys and to leave SecureBoot off.
-Additionally, it is possible to install the UKI in the default fallback path used by most UEFI implementations. By installing the UKI into this path, the system will automatically boot into it if no other entries are defined. This can be automated as part of the kernel hook by adding the following to {{path|/etc/kernel-hooks.d/secureboot.conf}}
+Additionally, it is possible to install the UKI in the default fallback path used by most UEFI implementations. By installing the UKI into this path, the system will automatically boot into it if no other entries are defined. This can be automated as part of the kernel hook by adding the following to {{path|/etc/kernel-hooks.d/secureboot.conf}} :
 {{cat|/etc/kernel-hooks.d/secureboot.conf|<nowiki># For the edge kernel, install the UKI into the default UEFI path.
@@ Line 178: / Line 177: @@
 </nowiki>}}
-{{path|bootx64.efi}} is only correct for <code>x86_64</code> systems. For other architectures the exact name will vary.
+{{Note|  {{path|bootx64.efi}} is only correct for <code>x86_64</code> systems. For other architectures, the exact name will vary.}}
 == See also ==