Bootloaders

2026-03-18T17:32:38Z

Ironswordx: Add the normal 32-bit EFI file name.

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:-

* <code>[[#Syslinux|Syslinux]]</code> is the default lightweight bootloader used in Alpine Linux when booting the Alpine Installer ISO. It is also the bootloader when creating a Live USB/CD/ISOLinux/PXELinux. Supports the Filesystems: FAT12/16/32
* <code>[[#Extlinux|Extlinux]]</code> is the default lightweight bootloader used in Alpine Linux when Installing the Alpine OS to Disk via BIOS/Legacy Boot. Supports the Filesystems: EXT2/3/4, BTRFS, XFS<br>
* <code>[[#GRUB|GRUB]]</code> is a standard Linux bootloader used in Alpine Linux when Installing the Alpine OS to Disk via UEFI.
* <code>[[#Limine|Limine]]</code> is a modern, advanced, portable, multiprotocol bootloader and boot manager.
* <code>[[#EFI_Boot_Stub|EFI Boot Stub]]</code> allows for booting Linux directly from a motherboard supporting ''UEFI'' or from another bootloader.
* <code>[[#rEFInd|rEFInd]]</code> is an easy-to-use ''EFI'' boot menu that allows booting different operating systems.<br>
* [[UEFI Secure Boot]] uses {{pkg|systemd-efistub}} or {{pkg|stubbyboot-efistub}}.

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.

Note that {{pkg|gummiboot}} is a ''deprecated'' UEFI boot manager that was originally able to leverage UEFI firmware and detect bootable images such as Linux kernels that have an EFI stub on the EFI System Partition (ESP). The [https://cgit.freedesktop.org/gummiboot/ gummiboot project] was discontinued in 2015 and renamed as {{Pkg|systemd-boot}} for systemd systems and is only available in Alpine Linux in the [[Repositories#Testing|testing repository]]. As it had no runtime dependencies, '''gummiboot''' was appreciated for its simplicity as a lightweight, minimal UEFI boot solution. Its UEFI stub, {{pkg|gummiboot-efistub}}, was used [[UEFI_Secure_Boot#Generating_Unified_Kernel_Image|to generate a Unified Kernel Images (UKIs)]] e.g. for [[DM-verity]] and Secure Boot, but [[Release_Notes_for_Alpine_3.22.0#Secure_Boot_and_Gummiboot|it has been deprecated since Alpine Linux 3.22]] and is no longer maintained; it has been replaced by '''systemd-efistub''' (note that the latter package [[UEFI_Secure_Boot#Generating_Unified_Kernel_Image|only supplies EFI stub binaries]] and doesn’t depend on any systemd components).

== 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 {{pkg|syslinux}} package:

{{cmd|# 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, {{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, 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>}}


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|# syslinux --install /boot}}

The configuration file is located in {{path|/boot/syslinux/syslinux.cfg}}.

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 edit and add additional menu entries in the bootloader configuration file for dual booting multiple os's: {{path|/boot/syslinux/syslinux.cfg}}

=== 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 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
# 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/
</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), 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:

{{cat|/mnt/EFI/syslinux/syslinux.cfg|<nowiki>...
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-mod,usb-storage,ext4 quiet
</nowiki>}}

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:

'''efibootmgr'''
<pre>
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)
</pre>

== GRUB ==

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

{{cmd|<nowiki># apk del syslinux
# apk add grub grub-bios
</nowiki>}}

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:

{{cmd|# grub-install /dev/vda}}

For EFI mode:

{{cmd|<nowiki># grub-install --target=x86_64-efi --efi-directory=/boot</nowiki>}}

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 configuration generator, including some automatic detection of other operating systems installed on the device:

{{cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

This script can be configured via the {{path|/etc/default/grub}} file.

If the font in the GRUB boot screen appears too small, then [[Fonts#Changing_GRUB_font_and_font_size|change the GRUB font]].

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.

== Limine ==

[https://codeberg.org/Limine/Limine Limine] is a modern, advanced, portable, multiprotocol bootloader and boot manager, also used as the reference implementation for the Limine boot protocol. It supports partitioning schemes like MBR, GPT and Unpartitioned media.

== 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 {{Pkg|efibootmgr}}:
{{cmd|# apk add efibootmgr}}

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

{{cat|add-bootentry|<nowiki>#!/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
</nowiki>}}

Where {{path|/dev/sdXY}} contains the EFI partition and {{path|/dev/sdXZ}} contains the root partition. If you are using {{Pkg|linux-stable}}, then replace <code>lts</code> with <code>stable</code> in the script.

{{Tip|If you're modifying EFI records from a running system (e. g. migrating from GRUB), you can populate {{ic|$params}} from {{ic|/proc/cmdline}}. Make sure to append {{ic|initrd}} param if it's missing since GRUB does not add it to the command line.}}

{{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.
}}

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

{{cmd|# efibootmgr -n XXXX}}

Where <code>XXXX</code> 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 {{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/}}. }}

== rEFInd ==
{{Main|rEFInd}}

[[rEFInd]] provides a graphical boot menu for [[UEFI]] systems.
== Using a UKI ==

'''[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 [[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}} :

{{cat|/etc/kernel-hooks.d/secureboot.conf|<nowiki># For the stable kernel, install the UKI into the default UEFI path.
if [ "$1" == "stable" ]; then
output_dir="/efi/EFI/Boot/"
output_name="bootx64.efi"
fi
</nowiki>}}

{{Note| {{path|bootx64.efi}} is only correct for <code>x86_64</code> systems. {{path|bootia32.efi}} is most commonly used on <code>x86</code> (32-bit) systems. For other architectures, the exact name will vary.}}

== Troubleshooting ==

Since bootloaders are installed only during [[System Disk Mode]], the errors related to them are documented in [[System Disk Mode#Troubleshooting|that page]].

== See also ==
* [[Enable Serial Console on Boot]]
* [[Silent boot]]
* [https://wiki.gentoo.org/wiki/Bootloader Gentoo Wiki - Bootloaders]
* [https://wiki.archlinux.org/title/Arch_boot_process#Boot_loader Archwiki - Boot loader]
* [https://wiki.postmarketos.org/wiki/Category:Bootloaders PostmarketOS Wiki - Bootloaders]
* [https://docs.u-boot.org/en/latest/develop/release_cycle.html u-boot.org docs - U-Boot Release Cycle]

[[Category:Installation]]
[[Category:Booting]]

Alpine Linux - User contributions [en]

Bootloaders