Bootloaders: Difference between revisions

From Alpine Linux
(Changed the Introduction paragraph and re-enabled EFI on syslinux section)
 
(47 intermediate revisions by 13 users not shown)
Line 1: Line 1:
By default Alpine uses Syslinux as bootloader.
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.
This page shows the basic steps you need to perform, if you for any reason want to switch bootloaders or apply some manual configuration.


The following bootloaders are available in Alpine Linux.


= Installing Syslinux =
* <code>[[#Syslinux|Syslinux]]</code> is the default light-weight bootloader used in Alpine.<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>[[#EFI_Boot_Stub|EFI Boot Stub]]</code> allows booting linux directly from a motherboard supporting UEFI or another bootloader.<br>
* Gummiboot can be used for [[UEFI Secure Boot]].


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.
== rEFInd ==


Install the <code>syslinux</code> package:
For (U)EFI systems, the {{pkg|refind}} package can provide a graphical EFI boot menu that allows to boot operating systems that are found on the available partitions.


<pre>apk add syslinux</pre>
As of now, {{pkg|refind}}  is available in the [[Repositories#Testing|testing]] repository. It can be safely installed in alpine by following the [[Repositories#Using_testing_repository|guidelines]] or it may be installed in other dual/multi-booted linux distribution.


If you're using GPT partitions, install the GPT MBR onto the drive you want to install the bootloader on (in this case <code>/dev/sda</code>):
The below command installs the alpine-linux refind package:
{{cmd|# apk add refind@testing }} 


<pre>dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/gptmbr.bin of=/dev/sda</pre>
The below command installs refind to the EFI partition
{{cmd| # refind-install --alldrivers}} 


Or if you're using DOS partitions, install the DOS MBR instead:
The <code>--alldrivers</code> option includes all filesystem drivers instead of only the one needed to load the currently running kernel, to allow finding and booting operating systems from more partitions.


<pre>dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=/dev/sda</pre>
For a Debian based distribution, it can be installed to the EFI partition like this:
{{cmd|<nowiki># apt install refind            # installs the debian package
# refind-install --alldrivers    # installs refind to the EFI partition
</nowiki>}}


<!-- See also: http://www.syslinux.org/wiki/index.php?title=Mbr -->
And a first (default) boot menu line needs to be configured with Alpine's default boot parameters. Assuming the bootable partition is mounted at {{path|/media/sdXY}} it can be done like this (at time of writing):
{{cmd|<nowiki># echo '"Alpine" "modules=loop,squashfs,sd-mod,usb-storage quiet initrd=\boot\intel-ucode.img initrd=\boot\amd-ucode.img initrd=\boot\initramfs-lts"' > /media/sdXY/boot/refind_linux.conf</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, XFS, and UFS/FFS filesystems.
{{Note|At the time of writing, it was still needed to use backslashes in the .conf file.<br>
The path in the config file needs to be relative to the partition that the kernel resides on. If {{path|/boot}} resides on its own separate partition, then <code>\boot</code> needs to be removed from the paths.}}


<pre>extlinux --install /boot</pre>
There is also a second config file, '''refind.conf''' which is located inside the EFI partition. This file has to be edited manually, but it does not get affected by btrfs snapshot rollbacks.
The config file is self-explanatory.  The author's  [https://www.rodsbooks.com/refind/configfile.html website] is also extremely rich in information.


The configuration file is located in <code>/boot/extlinux.conf</code>.
For [[btrfs]] filesystem, the necessary boot entry for Alpine Linux is as follows:
Alpine ships with a script called <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 <code>/etc/update-extlinux.conf</code>, including the option to disable automatic overwriting of <code>/boot/extlinux.conf</code>.
You can also place additional menu entries in the <code>/etc/update-extlinux.d/</code> directory, e.g. for dual booting.


{{Cat|/boot/efi/EFI/refind/refind.conf|
<nowiki>menuentry "Alpine Linux" {
    icon    /EFI/refind/icons/os_alpine.png
    volume  BTRFSVOL
    loader  @alpine/boot/vmlinuz-lts
    initrd  @alpine/boot/initramfs-lts
    options  "root=UUID=823a3283-30a7-4fef-b50b-8a2230c71b5b rw rootflags=subvol=@alpine rootfstype=btrfs"
    # PARTUUID not working for alpine
}
</nowiki>
}}


== EFI ==
For default alpine [[Installation#System_Disk_Mode|sys]] mode installation, the complete file content of refind.conf necessary to [[Dualbooting|dual boot]] Alpine Linux and windows is as follows:


{{Todo|Work in progress. This should at least get you started.}}
{{Cat|/boot/efi/EFI/refind/refind.conf|
<nowiki>
timeout 20
resolution 1920 1080
use_graphics_for windows,linux


Assuming <code>/mnt</code> is a FAT32 partition of type EF00 and <code>/boot</code> belongs to the rootfs created after running <code>setup-disk</code>:
menuentry "Windows" {
  loader /EFI/Microsoft/Boot/bootmgfw.efi
  icon /EFI/refind/icons/os_win.png
}
menuentry "Alpine Linux" {
    icon    /EFI/refind/icons/os_alpine.png
    volume  ROOT
    loader  /boot/vmlinuz-lts
    initrd  /boot/initramfs-lts
    options  "root=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx rw"
</nowiki>  
}}


<pre>
The  {{pkg|refind}} utility currently does not have Alpine Linux icon file. You can place this [[Media:Os alpine.png| icon]] in /boot/efi/EFI/refind/icons/ folder.
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/
cp /boot/initramfs* /mnt/
</pre>


You may need to modify <code>/mnt/EFI/syslinux/syslinux.cfg</code> to change the paths to absolute paths (just add a / in front of the vmlinuz/initramfs entries),
{{Tip|If the above configuration is working perfectly,there is no need for {{pkg|grub}} and can be safely removed.}}
or copy the files to <code>/mnt/EFI/syslinux</code> instead (XXX: untested).


= GRUB =
== Syslinux ==


To install GRUB in BIOS mode, (optionally) remove the Syslinux package and install the required GRUB packages:
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.


<pre>apk del syslinux
Install the {{pkg|syslinux}} package:
apk add grub grub-bios</pre>


For EFI, install Grub's EFI package instead. Note that <code>/boot</code> has to be an EFI compatible filesystem like FAT32.
{{cmd|# apk add syslinux}}


<pre>apk add grub-efi</pre>
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}}):


Next install the MBR and GRUB binaries to disk for BIOS mode:
{{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/gptmbr.bin of=/dev/sda</nowiki>}}


<pre>grub-install /dev/vda</pre>
Or if you're using DOS partitions, install the DOS MBR instead:


For EFI mode:
{{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=/dev/sda</nowiki>}}


<pre>grub-install --target=x86_64-efi --efi-directory=/boot</pre>
<!-- See also: http://www.syslinux.org/wiki/index.php?title=Mbr -->


GRUB ships with an automatic config generator, including some automatic detection of other operating systems installed on the device:
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.


<pre>grub-mkconfig -o /boot/grub/grub.cfg</pre>
{{cmd|# extlinux --install /boot}}


This script can be configured via the <code>/etc/default/grub</code> file.
The configuration file is located in {{path|/boot/extlinux.conf}}.  
See [https://www.gnu.org/software/grub/manual/html_node/Simple-configuration.html] for a list of available options.


= systemd-boot=
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}}.


{{Todo|Work in progress. It is mostly done in Linux basics but doesn't cover topics like creating entries for other Operating Systems.}}
You can also place additional menu entries in the {{path|/etc/update-extlinux.d/}} directory, e.g. for dual booting.


Systemd-boot is the simple EFI bootloader part of the systemd project. It is also available in the Alpine Linux testing repository as a standalone component.
=== Using EFI with syslinux ===


== Installing ==
Alpine Linux installer automatically uses [[#GRUB|Grub]], if EFI mode is detected. The below section is specifically about using EFI with syslinux:


To install the systemd-boot, enable the testing repository, and install the <code>systemd-boot</code> package. Then make sure the boot and EFI partitions are mounted as read-write and install the bootloader with <code>bootctl</code>.
Assuming {{path|/mnt}} is a FAT32 partition of type EF00 and {{path|/boot}} belongs to the rootfs created after running <code>setup-disk</code>:


<pre>
{{cmd|<nowiki># mkdir -p /mnt/EFI/syslinux
# apk add systemd-boot
# cp /usr/share/syslinux/efi64/* /mnt/EFI/syslinux/
# bootctl install
# cp /boot/extlinux.conf /mnt/EFI/syslinux/syslinux.cfg
</pre>
# cp /boot/vmlinuz* /mnt/EFI/syslinux/
# cp /boot/initramfs* /mnt/EFI/syslinux/
</nowiki>}}


The <code>bootctl</code> binary also has support for checking if the bootloader is installed.
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).


<pre>
At the end, the file {{path|/mnt/EFI/syslinux/syslinux.cfg}} should look like this:
# bootctl is-installed
{{cat|/mnt/EFI/syslinux/syslinux.cfg|<nowiki>...
yes
DEFAULT menu.c32
</pre>
PROMPT 0
 
MENU TITLE Alpine/Linux Boot Menu
== Configuring ==
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
</nowiki>}}


Example configuration files for alpine are available on <code>/usr/share/systemd/bootctl</code> as <code>loader.conf</code> and <code>alpine.conf</code>.
And finally, add syslinux to EFI boot menu (assuming {{path|/dev/sda}} is your hard drive)
{{cmd|<nowiki># apk add efibootmgr
# efibootmgr -c -d /dev/sda -p 1 -l \\EFI\\syslinux\\syslinux.efi -L "ALPINE-SYSLINUX"
</nowiki>}}


The bootloader (not the boot entries) can be configured via the [https://www.freedesktop.org/software/systemd/man/loader.conf.html# loader.conf] file, an example is available in <code>/usr/share/systemd/bootctl/loader.conf</code>.
You can now verify that the boot entry has been added


'''efibootmgr'''
<pre>
<pre>
# cp /usr/share/systemd/bootctl/loader.conf /boot/loader
BootCurrent: 0001
# vi /boot/loader/loader.conf
Timeout: 0 seconds
BootOrder: 0001,0000,0002,...
Boot001* ALPINE-SYSLINUX HD(1,GPT,xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)/FILE(\EFI\syslinux\syslinux.efi)
</pre>
</pre>


systemd-boot makes use of configuration files in <code>/boot/loader/entries</code> to list entries for different OSes it can boot into. An example file for Alpine Linux is present on <code>/usr/share/systemd/bootctl/alpine.conf</code>.
== GRUB ==


<pre>
To install GRUB in BIOS mode, (optionally) remove the Syslinux package and install the required GRUB packages:
# cp /usr/share/systemd/bootctl/alpine.conf /boot/loader/entries
# vi /boot/loader/entries/alpine.conf
</pre>


The example file has a skeleton structure that requires minimal modifications to make them work. You need to modify the example file to fit your oeprating system, among them:
{{cmd|<nowiki># apk del syslinux
# apk add grub grub-bios
</nowiki>}}


* Replace root=UUID=XXXX with the UUID of the root partition.
For EFI, install GRUB's EFI package instead. Note that {{path|/boot}} has to be an EFI compatible filesystem like FAT32.
* Replace rootfstype with the filesystem used for the root filesystem.
* Add boot options required/recommended for booting your operating system (E.g: cryptdm=, cryptroot=, modules=, etc).
* (If you don't use the default linux-lts kernel) Replace vmlinuz-lts and initramfs-lts with the ones that are used.
* (If you use an Intel CPU and need Intel microcode) add <code>initrd /intel-ucode.img</code> before the initrd call for the initramfs 


All the options available are documented in the [https://systemd.io/BOOT_LOADER_SPECIFICATION/ systemd boot loader specification] under Technical Details.
{{cmd|# apk add grub-efi efibootmgr}}


=== Unified Kernel Images ===
Next install the MBR and GRUB binaries to disk for BIOS mode:


Systemd-boot also accepts unified kernel images, as outlined in their [https://systemd.io/BOOT_LOADER_SPECIFICATION/#type-2-efi-unified-kernel-images document]. They are a combination of various pieces that are usually separate when normally booting, like the kernel, the initramfs and the kernel commandline.
{{cmd|# grub-install /dev/vda}}


To generate a unified kernel image the <code>objcopy</code> binary can be used:
For EFI mode:


<pre>
{{cmd|<nowiki># grub-install --target=x86_64-efi --efi-directory=/boot</nowiki>}}
# objcopy \
--add-section .osrel="/etc/os-release" --change-section-vma .osrel=0x20000 \
--add-section .cmdline="/proc/cmdline" --change-section-vma .cmdline=0x30000 \
--add-section .linux="$(bootctl -x)/vmlinuz-lts" --change-section-vma .linux=0x40000 \
--add-section .initrd="$(bootctl -x)/initramfs-lts" --change-section-vma .initrd=0x3000000 \
/usr/lib/systemd/boot/efi/linuxx64.efi.stub $(bootctl -p)/EFI/Linux/linux.efi
</pre>


The above can be signed, with the bootloader, for use in Secure Boot.
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>}}


Users that also require CPU microcode (like intel-ucode) can also include it by concatenating the CPU microcode .img file before the normal initramfs into a single .img file.
GRUB ships with an automatic config generator, including some automatic detection of other operating systems installed on the device:


<pre>
{{cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}
# cat $(bootctl -x)/cpu_microcode.img $(bootctl -x)/initramfs-lts > /tmp/initramfs-lts
</pre>


Then use that in the .initrd section of the <code>objcopy</code> call.
This script can be configured via the {{path|/etc/default/grub}} file.
See [https://www.gnu.org/software/grub/manual/html_node/Simple-configuration.html] for a list of available options.


== Listing Information and Status ==
== EFI Boot Stub ==


<code>bootctl</code> can also list the entries available, which one is default and a wealth of information from them. (Example from Alpine Linux developer Leo, which inculdes an entry and a Unified Kernel Image)
To boot directly from your motherboard's UEFI boot menu, a boot entry needs
to be created with either a UEFI shell or ''efibootmgr''.


<pre>
=== efibootmgr ===
# bootctl list
Boot Loader Entries:
        title: Alpine Linux
          id: alpine
      source: /boot/loader/entries/alpine.conf
        linux: /vmlinuz-lts
      initrd: /intel-ucode.img
              /initramfs-lts
      options: root=UUID=1437f4dd-7efd-4a4e-8fac-797b548076d1 cryptdm=pool cryptroot=/dev/sda2 modules=ext4,xfs rootfstype=ext4 psi=1 quiet


        title: Alpine Linux edge (default)
Install efibootmgr:
          id: alpine-3.12_alpha20200122
{{cmd|# apk add efibootmgr}}
      source: /boot/EFI/Linux/linux.efi
        linux: EFI/Linux/linux.efi
      options: initrd=\intel-ucode.img initrd=\initramfs-lts root=UUID=1437f4dd-7efd-4a4e-8fac-797b548076d1 cryptdm=pool cryptroot=/dev/sda2 modules=ext4,xfs rootfstype=ext4 psi=1 quiet


        title: Reboot Into Firmware Interface
Create a boot entry. It's recommended to do this in a script, as efibootmgr
          id: auto-reboot-to-firmware-setup
does not allow editing entries.
      source: /sys/firmware/efi/efivars/LoaderEntries-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
</pre>


And it can also list general status of the system, including information on the current bootloader, the system firmware and options (like if Secure Boot is enabled).
{{cat|add-bootentry|<nowiki>#!/bin/sh


<pre>
params="root=/dev/sdXZ rootfstype=ext4 rw \
# bootctl status
  initrd=\intel-ucode.img \
System:
   initrd=\initramfs-lts"
    Firmware: UEFI 2.40 (American Megatrends 5.11)
   Secure Boot: enabled
  Setup Mode: user


Current Boot Loader:
efibootmgr --create --label "Alpine Linux" \
      Product: systemd-boot 243
  --disk /dev/sdX --part Y \
    Features: ✓ Boot counting
  --loader /vmlinuz-lts \
              ✓ Menu timeout control
  --unicode "${params}" \
              ✓ One-shot menu timeout control
  --verbose
              ✓ Default entry control
</nowiki>}}
              ✓ One-shot entry control
              ✓ Support for XBOOTLDR partition
              ✓ Support for passing random seed to OS
        Stub: systemd-stub 243
          ESP: /dev/disk/by-partuuid/00e7649e-bf1f-481b-87cd-7228af8c118f
        File: └─/EFI/systemd/systemd-bootx64.efi


Random Seed:
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
Passed to OS: no
System Token: set
      Exists: yes


Available Boot Loaders on ESP:
{{Note|
          ESP: /boot (/dev/disk/by-partuuid/00e7649e-bf1f-481b-87cd-7228af8c118f)
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.
        File: └─/EFI/systemd/systemd-bootx64.efi (systemd-boot 243)
}}
        File: └─/EFI/BOOT/BOOTX64.EFI (systemd-boot 243)


Boot Loaders Listed in EFI Variables:
Optionally, set the newly created entry as the default:
        Title: Linux Boot Manager
          ID: 0x0007
      Status: active, boot-order
    Partition: /dev/disk/by-partuuid/00e7649e-bf1f-481b-87cd-7228af8c118f
        File: └─/EFI/systemd/systemd-bootx64.efi


        Title: Windows Boot Manager
{{cmd|# efibootmgr -n XXXX}}
          ID: 0x0000
      Status: active
    Partition: /dev/disk/by-partuuid/fd36bbae-be4f-409a-b1ce-14771e091067
        File: └─/EFI/Microsoft/Boot/bootmgfw.efi


Boot Loader Entries:
Where <code>XXXX</code> is the boot number of the new entry.
        $BOOT: /boot (/dev/disk/by-partuuid/00e7649e-bf1f-481b-87cd-7228af8c118f)


Default Boot Loader Entry:
{{Note|
        title: Alpine Linux edge
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/}}.                                                                                          }}
          id: alpine-3.12_alpha20200122
      source: /boot/EFI/Linux/linux.efi
        linux: EFI/Linux/linux.efi
      options: initrd=\intel-ucode.img initrd=\initramfs-lts root=UUID=1437f4dd-7efd-4a4e-8fac-797b548076d1 cryptdm=pool cryptroot=/dev/sda2 modules=ext4,xfs rootfstype=ext4 psi=1 quiet
</pre>


== Updating ==
== Using a UKI  ==


When the <code>systemd-boot</code> package is updated the bootloader installed needs to be updated as well:
'''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. While this is typically done in order to enable [https://en.wikipedia.org/wiki/UEFI SecureBoot], it is perfectly feasible to skip enrolling the custom keys and leave SecureBoot off.


<pre>
The page [[UEFI Secure Boot]] contains the instructions for setting an a UKI. 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}}
# bootctl update
</pre>
 
== Removing ==


If for any reason you wish to not use systemd-boot anymore then the <code>bootctl</code> binary also provides a command for easily removing the files that were installed with the install command:
{{cat|/etc/kernel-hooks.d/secureboot.conf|<nowiki># 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
</nowiki>}}


<pre>
{{path|bootx64.efi}} is only correct for <code>x86_64</code> systems. For other architectures the exact name will vary.
# bootctl remove
# apk del systemd-boot
</pre>


= External Links =
= See also =
* [https://wiki.gentoo.org/wiki/Bootloader Gentoo Wiki]
* [https://wiki.archlinux.org/title/Arch_boot_process#Boot_loader Archwiki]
* [https://wiki.postmarketos.org/wiki/Category:Bootloaders PostmarketOS Wiki]
* [https://www.denx.de/wiki/U-Boot/ReleaseCycle U-Boot Release Cycle]
* [https://www.denx.de/wiki/U-Boot/ReleaseCycle U-Boot Release Cycle]
* [https://wiki.archlinux.org/index.php/systemd-boot ArchWiki extensive article on systemd-boot]


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

Latest revision as of 09:37, 16 December 2024

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.

The following bootloaders are available in Alpine Linux.

  • Syslinux is the default light-weight bootloader used in Alpine.
  • rEFInd is an easy to use EFI boot menu that allows booting different operating systems.
  • GRUB is a standard linux boot loader.
  • EFI Boot Stub allows booting linux directly from a motherboard supporting UEFI or another bootloader.
  • Gummiboot can be used for UEFI Secure Boot.

rEFInd

For (U)EFI systems, the refind package can provide a graphical EFI boot menu that allows to boot operating systems that are found on the available partitions.

As of now, refind is available in the testing repository. It can be safely installed in alpine by following the guidelines or it may be installed in other dual/multi-booted linux distribution.

The below command installs the alpine-linux refind package:

# apk add refind@testing

The below command installs refind to the EFI partition

# refind-install --alldrivers

The --alldrivers option includes all filesystem drivers instead of only the one needed to load the currently running kernel, to allow finding and booting operating systems from more partitions.

For a Debian based distribution, it can be installed to the EFI partition like this:

# apt install refind # installs the debian package # refind-install --alldrivers # installs refind to the EFI partition

And a first (default) boot menu line needs to be configured with Alpine's default boot parameters. Assuming the bootable partition is mounted at /media/sdXY it can be done like this (at time of writing):

# echo '"Alpine" "modules=loop,squashfs,sd-mod,usb-storage quiet initrd=\boot\intel-ucode.img initrd=\boot\amd-ucode.img initrd=\boot\initramfs-lts"' > /media/sdXY/boot/refind_linux.conf

Note: At the time of writing, it was still needed to use backslashes in the .conf file.
The path in the config file needs to be relative to the partition that the kernel resides on. If /boot resides on its own separate partition, then \boot needs to be removed from the paths.

There is also a second config file, refind.conf which is located inside the EFI partition. This file has to be edited manually, but it does not get affected by btrfs snapshot rollbacks. The config file is self-explanatory. The author's website is also extremely rich in information.

For btrfs filesystem, the necessary boot entry for Alpine Linux is as follows:

Contents of /boot/efi/EFI/refind/refind.conf

menuentry "Alpine Linux" { icon /EFI/refind/icons/os_alpine.png volume BTRFSVOL loader @alpine/boot/vmlinuz-lts initrd @alpine/boot/initramfs-lts options "root=UUID=823a3283-30a7-4fef-b50b-8a2230c71b5b rw rootflags=subvol=@alpine rootfstype=btrfs" # PARTUUID not working for alpine }

For default alpine sys mode installation, the complete file content of refind.conf necessary to dual boot Alpine Linux and windows is as follows:

Contents of /boot/efi/EFI/refind/refind.conf

timeout 20 resolution 1920 1080 use_graphics_for windows,linux menuentry "Windows" { loader /EFI/Microsoft/Boot/bootmgfw.efi icon /EFI/refind/icons/os_win.png } menuentry "Alpine Linux" { icon /EFI/refind/icons/os_alpine.png volume ROOT loader /boot/vmlinuz-lts initrd /boot/initramfs-lts options "root=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx rw" }

The refind utility currently does not have Alpine Linux icon file. You can place this icon in /boot/efi/EFI/refind/icons/ folder.

Tip: If the above configuration is working perfectly,there is no need for grub and can be safely removed.

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.

Install the syslinux package:

# 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 /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, 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 ships with a script update-extlinux which 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

Alpine Linux installer automatically uses Grub, if EFI mode is detected. The below section is specifically about using EFI with syslinux:

Assuming /mnt is a FAT32 partition of type EF00 and /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).

At the end, the file /mnt/EFI/syslinux/syslinux.cfg 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

And finally, add syslinux to EFI boot menu (assuming /dev/sda is your hard drive)

# 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)

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 like 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 config 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. See [1] for a list of available options.

EFI Boot Stub

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

efibootmgr

Install efibootmgr:

# apk add efibootmgr

Create a boot entry. It's recommended to do this in a script, as efibootmgr does not allow 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, 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 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 which contains the initfs, kernel and cmdline. While this is typically done in order to enable SecureBoot, it is perfectly feasible to skip enrolling the custom keys and leave SecureBoot off.

The page UEFI Secure Boot contains the instructions for setting an a UKI. 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

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

See also