Bootloaders: Difference between revisions

From Alpine Linux
mNo edit summary
m (Typo)
 
(32 intermediate revisions by 11 users not shown)
Line 2: Line 2:
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.


<code>Syslinux</code> is the default light-weight bootloader used in Alpine.<br>
* <code>[[#Syslinux|Syslinux]]</code> is the default light-weight bootloader used in Alpine.<br>
<code>rEFInd</code> is an easy to use 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</code> is a standard linux boot loader.<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]].


= rEFInd =


 
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.
= rEFIind =
 
For (U)EFI systems, the <code>refind</code> package can provide a nice EFI boot menu that allows booting different operating system from the available partitions.


If <code>refind</code> is not yet available in the used alpine release, it may be installed in another dual/multi-booted linux distribution.
If <code>refind</code> is not yet available in the used alpine release, it may be installed in another dual/multi-booted linux distribution.


For example, with a Debian based distribution, it can be done like this:
For example, with a Debian based distribution, it can be installed to the EFI partition like this:
   
   
apt install refind
{{cmd|<nowiki># apt install refind             # installs the debian package
refind-install
# refind-install --alldrivers    # installs refind to the EFI partition
cp /usr/share/refind/refind/drivers_x64/ext4_x64.efi /boot/efi/EFI/refind/drivers_x64/
</nowiki>}}


(Also enables the ext4 driver, to allow finding and booting Linux installations from ext4 partitions.)
(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.)


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


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


= Installing Syslinux =
= 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 you for some reason want to install Syslinux manually, the following steps are required.


Install the <code>syslinux</code> package:
Install the {{pkg|syslinux}} package:


<pre>apk add syslinux</pre>
{{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 <code>/dev/sda</code>):
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}}):


<pre>dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/gptmbr.bin of=/dev/sda</pre>
{{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, install the DOS MBR instead:


<pre>dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=/dev/sda</pre>
{{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 -->
<!-- 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, 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.


<pre>extlinux --install /boot</pre>
{{cmd|# extlinux --install /boot}}


The configuration file is located in <code>/boot/extlinux.conf</code>.
The configuration file is located in {{path|/boot/extlinux.conf}}.
Alpine ships with a script called <code>update-extlinux</code> which automatically (re)generates this file, for example on updates to Syslinux.
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>.
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 <code>/etc/update-extlinux.d/</code> 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.




== EFI ==
=== EFI ===


{{Todo|Work in progress. This should at least get you started.}}
{{Todo|Work in progress. This should at least get you started.}}


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>:
Assuming {{path|/mnt}} is a FAT32 partition of type EF00 and {{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).
 
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
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
</nowiki>}}
 
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>}}
 
You can now verify that the boot entry has been added


'''efibootmgr'''
<pre>
<pre>
mkdir -p /mnt/EFI/syslinux
BootCurrent: 0001
cp /usr/share/syslinux/efi64/* /mnt/EFI/syslinux/
Timeout: 0 seconds
cp /boot/extlinux.conf /mnt/EFI/syslinux/syslinux.cfg
BootOrder: 0001,0000,0002,...
cp /boot/vmlinuz* /mnt/
Boot001* ALPINE-SYSLINUX HD(1,GPT,xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)/FILE(\EFI\syslinux\syslinux.efi)
cp /boot/initramfs* /mnt/
</pre>
</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),
or copy the files to <code>/mnt/EFI/syslinux</code> instead (XXX: untested).


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


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


For EFI, install Grub's EFI package instead. Note that <code>/boot</code> 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 like FAT32.


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


<pre>grub-install /dev/vda</pre>
{{cmd|# grub-install /dev/vda}}


For EFI mode:
For EFI mode:


<pre>grub-install --target=x86_64-efi --efi-directory=/boot</pre>
{{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 config generator, including some automatic detection of other operating systems installed on the device:
GRUB ships with an automatic config generator, including some automatic detection of other operating systems installed on the device:


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


This script can be configured via the <code>/etc/default/grub</code> file.
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.
See [https://www.gnu.org/software/grub/manual/html_node/Simple-configuration.html] for a list of available options.


= External Links =
= 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:
{{cmd|# apk add efibootmgr}}
 
Create a boot entry. It's recommended to do this in a script, as efibootmgr
does not allow 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-edge}}, replace <code>lts</code> with <code>edge</code> in the script
 
{{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 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 (UEFI only) =
 
It is possible to boot directly into a '''Unified Kernel Image''' (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.
 
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}}
 
{{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>}}
 
{{path|bootx64.efi}} is only correct for <code>x86_64</code> systems. For other architectures the exact name will vary.
 
= 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]


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

Latest revision as of 16:34, 19 March 2024

This page shows the basic steps you need to perform, if you for any reason want to switch bootloaders or apply some manual configuration.

  • 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.

If refind is not yet available in the used alpine release, it may be installed in another dual/multi-booted linux distribution.

For example, with 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

(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.)

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.

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 called 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.


EFI

Todo: Work in progress. This should at least get you started.


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 (UEFI only)

It is possible to boot directly into a Unified Kernel Image (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