Alpine Linux - User contributions [en]

System Disk Mode

2026-02-12T23:45:01Z

Kenrmayfield: /* Check File System Kernel Modules are Loading */

System Disk mode is the traditional or classic harddisk installation of Alpine Linux. This installation mode is suitable for most use cases including generic [[Tutorials_and_Howtos#Desktop|desktop]], [[Setting up the build environment|development machine]] etc.

If an entire hard disk(s) is available for Alpine Linux, [[Installation#setup-alpine_based_System_Disk_Install|setup-alpine based install]] is the recommended way to install Alpine Linux. For all other use cases, follow the [[Alpine_setup_scripts#setup-disk|<code>setup-disk</code>]] based Installation given below.

== setup-disk based Installation ==

To perform a traditional hard-disk installation of Alpine Linux, after completing the base configuration, proceed to create, format and mount your partitions with MOUNTPOINT {{Path|'''/mnt'''}} as root and run the command {{Codeline|'''<Code>setup-disk -m sys /mnt</Code>'''}}.

# Follow the [[Installation#General_course_of_action|Installation guide]] to complete the [[Installation#Base_configuration|base configuration]], if not already done. A working [[Configure_Networking#Connectivity_testing|Internet access]] is mandatory to complete this installation.
# If necessary formatted partition(s) are unavailable, manually [[Setting up disks manually#Creating_partitions|create]] them first and [[Setting up disks manually#Formatting_partitions|format]] them including swap partition(if used). If you're using legacy BIOS mode, use DOS i.e MBR partition table and ensure that proper partition is bootable for [[Bootloaders#Syslinux|extlinux]].
# Mount the '''/ (root)''' partition on a mount point i.e say {{Path|/mnt}} as follows: {{Cmd|# mount /dev/sdXY /mnt}}
# If you're using [[UEFI|EFI]], create a mount point <code>/mnt/boot</code> and mount the EFI system partition(ESP) on it. {{Cmd|<nowiki># mkdir -p /mnt/boot
# mount /dev/sdXY /mnt/boot</nowiki>}}
# If [[Swap|swap]] partition is available, you can also enable it now: {{Cmd|# swapon /dev/sdXY }}
# Install Alpine Linux using the following command: {{Cmd|# setup-disk -m sys /mnt}}
# <code>setup-disk</code> will perform a traditional hard disk install of your running system, detects your file system layout and generates {{Path|/etc/fstab}} and installs a [[Bootloaders|bootloader]] based on the <Code>BOOTLOADER</Code> [[Alpine_setup_scripts#Environment_Variables|environment variable]].
# At the end of Installation, you can [[Installation#Reboot|reboot]] to boot into the newly installed Alpine Linux and [[Installation#Post-Installation|configure]] further.

== Troubleshooting ==

=== Mounting on /dev/sdXY sysroot failed ===

The error message appears as follows with variations in <code>/dev/sda8</code> depending on the partition number and SSD/HDD etc:

<Pre>
mounting /dev/sda8 on /sysroot failed: No such file or directory
mounting root: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot
sh: can't access tty: job control turned off
</Pre>

The above error message can be caused by various reasons. Follow the below steps in the emergency shell to identify one possible cause.

# Verify that the partition name in which Alpine Linux was installed matches the above [[#Mounting on /dev/sdXY sysroot failed|error]] by issuing the command and also note down the filesystem type of that partition (say TYPE="ext4") : {{Cmd| blkid}}
# If the expected disk (e.g., /dev/sda, /dev/nvme0n1) itself is missing in the output of {{ic| blkid}}, check [[#Disks not detected after setup-disk|Disks not detected after setup-disk]].
# Verify that sysroot exists by issuing the command. {{Cmd|ls -ld /sysroot}}
# Check if the above error message apears when issuing the command. {{Cmd|mount /dev/sda8 /sysroot}}
# If there is no error message, proceed to check if the issue is caused by a [[#Filesystem corruption|filesystem corruption]].
# If the manual mount command fails with "No such file or directory" even though you verified /sysroot exists in Step 3, this confirms the kernel doesn't recognize the filesystem type. Check whether filesystem modules(change ext4 if needed) are loaded by issuing the command. {{Cmd|<nowiki>lsmod | grep ext4 </nowiki>}}
# If there is no output, then it confirms that the above [[#Mounting on /dev/sdXY sysroot failed|issue]] is caused by [[#Missing filesystem modules in the kernel cmdline|missing filesystem module]].

==== Disks not detected after setup-disk====

After running the standard Alpine installation command: {{ic|setup-disk -m sys /mnt}} and rebooting, the system gives the error mentioned in [[#Mounting on /dev/sdXY sysroot failed|Mounting on /dev/sdXY sysroot failed]] with the expected disk (e.g., /dev/sda, /dev/nvme0n1) missing to show at the output of {{ic| blkid}}. This prevents booting into the installed system.

Issue: As per [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10615 bug report] this might be caused by BIOS storage controller being set to "RAID On (Intel Rapid Storage Technology)".

Resolution: Switch the storage mode in BIOS/UEFI: Go to BIOS → Storage or SATA/NVMe Operation. Change setting from:RAID On (Intel Rapid Storage Technology) to: AHCI or AHCI/NVMe.

==== Missing filesystem modules in the kernel cmdline ====

[[BusyBox]] mount command does not autoload modules, so need to add filesystem modules to the kernel cmdline. Even though alpine installer does this automatically, this has to be taken care of in case of manual disk install, particularly for [[Dualbooting|dualboot]] installations.

# To resolve, issue the command to load the appropriate filesystem module(say TYPE="ext4").{{Cmd|modprobe ext4}}
# To verify if the issue is resolved, reissue the command.{{Cmd|mount /dev/sda8 /sysroot}}
# If mount succeeded, issue the following command to boot into Alpine Linux. {{Cmd|exit}}

Choose the appropriate solution based on your use case for a permanent fix:

*If you are using [[Bootloaders#GRUB|grub]], then ensure that {{Codeline|GRUB_CMDLINE_LINUX}} line in the file {{Path|/etc/default/grub}} has the appropriate filesystem module <code>ext4</code> and <code>rootfstype=ext4</code> as follows: {{Cat|/etc/default/grub|<nowiki>...
GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4"
...</nowiki>}}

* If you are using [[Bootloaders#Syslinux|ExtLinux/SysLinux]], then ensure that {{Codeline|APPEND}} line in the file {{Path|/boot/extlinux.conf}} has <code>root=UUID=<UUID ID></code> or <code>root=/dev/sdXY</code> and the same matches the root path in the {{Path|/etc/fstab}} file. Also ensure that modules has the appropriate filesystem like <code>ext4</code> as follows: {{Cat|/boot/extlinux.conf|<nowiki>...
APPEND root=/dev/sdXY modules=sd-mod,usb-storage,ext4 quiet
# root=UUID=<UUID ID> can be used also in the APPEND Line.
...</nowiki>}}

{{Note|For both above cases, you may need to issue {{Codeline|update-grub}} or {{Codeline|update-extlinux}} after making above changes.}}

*For a solution independent of [[Bootloaders|bootloaders]], ensure that the file {{Path|/etc/mkinitfs/mkinitfs.conf}} has the necessary filesystem module in it. Refer [[Initramfs init|Initramfs]] page for more information and recreate initramfs image.

==== Filesystem corruption ====

To fix filesystem corruption issues, the command fsck must be run on the root partition. The root partition should be umounted before running fsck. Boot from a [[Rescue disk]] to run the fsck command on the root partition:{{Cmd|<nowiki># fsck -y /dev/<DEVICE></nowiki>}}

After running fsck, proceed to Reboot the Computer.

If the fsck Command does Fix the Corruption on the Root File System but the '''Error: Mounting Root Failed''' still persists then the next step would be to ReBuild the '''initramfs''' File System with the '''mkinitfs''' Command then Reboot. You need to '''Mount the Root Partition''' and [[Chroot]] into the Mounted Root Partition before running the mkinitfs Command as shown in the [[Initramfs init|initramfs]] page.

==== Check File System Kernel Modules are Loading ====

{{Cmd|<nowiki># lsmod | grep <File System></nowiki>}}
{{Note |<nowiki>File System = ext2, ext3, ext4, btrfs, xfs, fat</nowiki>|}}

* Run the Command to Output the File System Kernel Modules:

{{Cat |Console Command and Ouput|<nowiki>
alpinepc:~# lsmod | grep ext4

ext4 1155072 2
crc16 12288 1 ext4
mbcache 16384 1 ext4
jbd2 200704 1 ext4
</nowiki>}}
EXT4 = File System 
CRC16 = EXT4 Compression Support 
MBCACHE = MetaData Cache 
JBD2 = Journaling 

=== Blinking underscore ===

On a UEFI system, at the end of Installation after rebooting, the computer screen may appear with a '''blinking underscore'''. This may be due to the firmware not finding a valid boot entry.

The [[UEFI#EFI bootloaders|EFI bootloader]] entries are added without writing to NVRAM, thus preventing GRUB from calling {{ic|efibootmgr}}. In some cases the UEFI firmware may not boot from a bootloader without a valid NVRAM entry. In such cases, at the end of installation, instead of rebooting, manually add an entry for Alpine Linux in the NVRAM as follows:
* Install the {{pkg|efibootmgr}} package:{{Cmd|# apk add efibootmgr}}
* Adjust the device name {{ic|/dev/sdX}} and partition number {{ic|1}}, before issuing the command: {{Cmd|# efibootmgr --create --disk /dev/sdX --part 1 --label "Alpine" --loader '\EFI\alpine\grubx64.efi'}}

== See also ==

* [[Bootloaders]] - For information on GRUB, Syslinux and rEFInd
* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
* [[Installing Alpine Linux in a chroot|Installing Alpine Linux in a chroot]]
* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]

[[Category:Installation]]

System Disk Mode

2026-02-11T01:09:13Z

Kenrmayfield:

System Disk mode is the traditional or classic harddisk installation of Alpine Linux. This installation mode is suitable for most use cases including generic [[Tutorials_and_Howtos#Desktop|desktop]], [[Setting up the build environment|development machine]] etc.

If an entire hard disk(s) is available for Alpine Linux, [[Installation#setup-alpine_based_System_Disk_Install|setup-alpine based install]] is the recommended way to install Alpine Linux. For all other use cases, follow the [[Alpine_setup_scripts#setup-disk|<code>setup-disk</code>]] based Installation given below.

== setup-disk based Installation ==

To perform a traditional hard-disk installation of Alpine Linux, after completing the base configuration, proceed to create, format and mount your partitions with MOUNTPOINT {{Path|'''/mnt'''}} as root and run the command {{Codeline|'''<Code>setup-disk -m sys /mnt</Code>'''}}.

# Follow the [[Installation#General_course_of_action|Installation guide]] to complete the [[Installation#Base_configuration|base configuration]], if not already done. A working [[Configure_Networking#Connectivity_testing|Internet access]] is mandatory to complete this installation.
# If necessary formatted partition(s) are unavailable, manually [[Setting up disks manually#Creating_partitions|create]] them first and [[Setting up disks manually#Formatting_partitions|format]] them including swap partition(if used). If you're using legacy BIOS mode, use DOS i.e MBR partition table and ensure that proper partition is bootable for [[Bootloaders#Syslinux|extlinux]].
# Mount the '''/ (root)''' partition on a mount point i.e say {{Path|/mnt}} as follows: {{Cmd|# mount /dev/sdXY /mnt}}
# If you're using [[UEFI|EFI]], create a mount point <code>/mnt/boot</code> and mount the EFI system partition(ESP) on it. {{Cmd|<nowiki># mkdir -p /mnt/boot
# mount /dev/sdXY /mnt/boot</nowiki>}}
# If [[Swap|swap]] partition is available, you can also enable it now: {{Cmd|# swapon /dev/sdXY }}
# Install Alpine Linux using the following command: {{Cmd|# setup-disk -m sys /mnt}}
# <code>setup-disk</code> will perform a traditional hard disk install of your running system, detects your file system layout and generates {{Path|/etc/fstab}} and installs a [[Bootloaders|bootloader]] based on the <Code>BOOTLOADER</Code> [[Alpine_setup_scripts#Environment_Variables|environment variable]].
# At the end of Installation, you can [[Installation#Reboot|reboot]] to boot into the newly installed Alpine Linux and [[Installation#Post-Installation|configure]] further.

== Troubleshooting ==

=== Mounting on /dev/sdXY sysroot failed ===

The error message appears as follows with variations in <code>/dev/sda8</code> depending on the partition number and SSD/HDD etc:

<Pre>
mounting /dev/sda8 on /sysroot failed: No such file or directory
mounting root: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot
sh: can't access tty: job control turned off
</Pre>

The above error message can be caused by various reasons. Follow the below steps in the emergency shell to identify one possible cause.

# Verify that the partition name in which Alpine Linux was installed matches the above [[#Mounting on /dev/sdXY sysroot failed|error]] by issuing the command and also note down the filesystem type of that partition (say TYPE="ext4") : {{Cmd| blkid}}
# If the expected disk (e.g., /dev/sda, /dev/nvme0n1) itself is missing in the output of {{ic| blkid}}, check [[#Disks not detected after setup-disk|Disks not detected after setup-disk]].
# Verify that sysroot exists by issuing the command. {{Cmd|ls -ld /sysroot}}
# Check if the above error message apears when issuing the command. {{Cmd|mount /dev/sda8 /sysroot}}
# If there is no error message, proceed to check if the issue is caused by a [[#Filesystem corruption|filesystem corruption]].
# If the manual mount command fails with "No such file or directory" even though you verified /sysroot exists in Step 3, this confirms the kernel doesn't recognize the filesystem type. Check whether filesystem modules(change ext4 if needed) are loaded by issuing the command. {{Cmd|<nowiki>lsmod | grep ext4 </nowiki>}}
# If there is no output, then it confirms that the above [[#Mounting on /dev/sdXY sysroot failed|issue]] is caused by [[#Missing filesystem modules in the kernel cmdline|missing filesystem module]].

==== Disks not detected after setup-disk====

After running the standard Alpine installation command: {{ic|setup-disk -m sys /mnt}} and rebooting, the system gives the error mentioned in [[#Mounting on /dev/sdXY sysroot failed|Mounting on /dev/sdXY sysroot failed]] with the expected disk (e.g., /dev/sda, /dev/nvme0n1) missing to show at the output of {{ic| blkid}}. This prevents booting into the installed system.

Issue: As per [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10615 bug report] this might be caused by BIOS storage controller being set to "RAID On (Intel Rapid Storage Technology)".

Resolution: Switch the storage mode in BIOS/UEFI: Go to BIOS → Storage or SATA/NVMe Operation. Change setting from:RAID On (Intel Rapid Storage Technology) to: AHCI or AHCI/NVMe.

==== Missing filesystem modules in the kernel cmdline ====

[[BusyBox]] mount command does not autoload modules, so need to add filesystem modules to the kernel cmdline. Even though alpine installer does this automatically, this has to be taken care of in case of manual disk install, particularly for [[Dualbooting|dualboot]] installations.

# To resolve, issue the command to load the appropriate filesystem module(say TYPE="ext4").{{Cmd|modprobe ext4}}
# To verify if the issue is resolved, reissue the command.{{Cmd|mount /dev/sda8 /sysroot}}
# If mount succeeded, issue the following command to boot into Alpine Linux. {{Cmd|exit}}

Choose the appropriate solution based on your use case for a permanent fix:

*If you are using [[Bootloaders#GRUB|grub]], then ensure that {{Codeline|GRUB_CMDLINE_LINUX}} line in the file {{Path|/etc/default/grub}} has the appropriate filesystem module <code>ext4</code> and <code>rootfstype=ext4</code> as follows: {{Cat|/etc/default/grub|<nowiki>...
GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4"
...</nowiki>}}

* If you are using [[Bootloaders#Syslinux|ExtLinux/SysLinux]], then ensure that {{Codeline|APPEND}} line in the file {{Path|/boot/extlinux.conf}} has <code>root=UUID=<UUID ID></code> or <code>root=/dev/sdXY</code> and the same matches the root path in the {{Path|/etc/fstab}} file. Also ensure that modules has the appropriate filesystem like <code>ext4</code> as follows: {{Cat|/boot/extlinux.conf|<nowiki>...
APPEND root=/dev/sdXY modules=sd-mod,usb-storage,ext4 quiet
# root=UUID=<UUID ID> can be used also in the APPEND Line.
...</nowiki>}}

{{Note|For both above cases, you may need to issue {{Codeline|update-grub}} or {{Codeline|update-extlinux}} after making above changes.}}

*For a solution independent of [[Bootloaders|bootloaders]], ensure that the file {{Path|/etc/mkinitfs/mkinitfs.conf}} has the necessary filesystem module in it. Refer [[Initramfs init|Initramfs]] page for more information and recreate initramfs image.

==== Filesystem corruption ====

To fix filesystem corruption issues, the command fsck must be run on the root partition. The root partition should be umounted before running fsck. Boot from a [[Rescue disk]] to run the fsck command on the root partition:{{Cmd|<nowiki># fsck -y /dev/<DEVICE></nowiki>}}

After running fsck, proceed to Reboot the Computer.

If the fsck Command does Fix the Corruption on the Root File System but the '''Error: Mounting Root Failed''' still persists then the next step would be to ReBuild the '''initramfs''' File System with the '''mkinitfs''' Command then Reboot. You need to '''Mount the Root Partition''' and [[Chroot]] into the Mounted Root Partition before running the mkinitfs Command as shown in the [[Initramfs init|initramfs]] page.

==== Check File System Kernel Modules are Loading ====

{{Cmd|<nowiki># lsmod | grep <File System></nowiki>}}
{{Note |<nowiki>File System = ext2, ext3, ext4, btrfs, xfs, fat</nowiki>|}}

* Run the Command to Output the File System Kernel Modules:

{{Cat |Console Ouput|<nowiki>
alpinepc:~# lsmod | grep ext4

ext4 1155072 2
crc16 12288 1 ext4
mbcache 16384 1 ext4
jbd2 200704 1 ext4
</nowiki>}}
EXT4 = File System 
CRC16 = EXT4 Compression Support 
MBCACHE = MetaData Cache 
JBD2 = Journaling 

=== Blinking underscore ===

On a UEFI system, at the end of Installation after rebooting, the computer screen may appear with a '''blinking underscore'''. This may be due to the firmware not finding a valid boot entry.

The [[UEFI#EFI bootloaders|EFI bootloader]] entries are added without writing to NVRAM, thus preventing GRUB from calling {{ic|efibootmgr}}. In some cases the UEFI firmware may not boot from a bootloader without a valid NVRAM entry. In such cases, at the end of installation, instead of rebooting, manually add an entry for Alpine Linux in the NVRAM as follows:
* Install the {{pkg|efibootmgr}} package:{{Cmd|# apk add efibootmgr}}
* Adjust the device name {{ic|/dev/sdX}} and partition number {{ic|1}}, before issuing the command: {{Cmd|# efibootmgr --create --disk /dev/sdX --part 1 --label "Alpine" --loader '\EFI\alpine\grubx64.efi'}}

== See also ==

* [[Bootloaders]] - For information on GRUB, Syslinux and rEFInd
* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
* [[Installing Alpine Linux in a chroot|Installing Alpine Linux in a chroot]]
* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]

[[Category:Installation]]

System Disk Mode

2026-02-11T00:55:40Z

Kenrmayfield:

System Disk mode is the traditional or classic harddisk installation of Alpine Linux. This installation mode is suitable for most use cases including generic [[Tutorials_and_Howtos#Desktop|desktop]], [[Setting up the build environment|development machine]] etc.

If an entire hard disk(s) is available for Alpine Linux, [[Installation#setup-alpine_based_System_Disk_Install|setup-alpine based install]] is the recommended way to install Alpine Linux. For all other use cases, follow the [[Alpine_setup_scripts#setup-disk|<code>setup-disk</code>]] based Installation given below.

== setup-disk based Installation ==

To perform a traditional hard-disk installation of Alpine Linux, after completing the base configuration, proceed to create, format and mount your partitions with MOUNTPOINT {{Path|'''/mnt'''}} as root and run the command {{Codeline|'''<Code>setup-disk -m sys /mnt</Code>'''}}.

# Follow the [[Installation#General_course_of_action|Installation guide]] to complete the [[Installation#Base_configuration|base configuration]], if not already done. A working [[Configure_Networking#Connectivity_testing|Internet access]] is mandatory to complete this installation.
# If necessary formatted partition(s) are unavailable, manually [[Setting up disks manually#Creating_partitions|create]] them first and [[Setting up disks manually#Formatting_partitions|format]] them including swap partition(if used). If you're using legacy BIOS mode, use DOS i.e MBR partition table and ensure that proper partition is bootable for [[Bootloaders#Syslinux|extlinux]].
# Mount the '''/ (root)''' partition on a mount point i.e say {{Path|/mnt}} as follows: {{Cmd|# mount /dev/sdXY /mnt}}
# If you're using [[UEFI|EFI]], create a mount point <code>/mnt/boot</code> and mount the EFI system partition(ESP) on it. {{Cmd|<nowiki># mkdir -p /mnt/boot
# mount /dev/sdXY /mnt/boot</nowiki>}}
# If [[Swap|swap]] partition is available, you can also enable it now: {{Cmd|# swapon /dev/sdXY }}
# Install Alpine Linux using the following command: {{Cmd|# setup-disk -m sys /mnt}}
# <code>setup-disk</code> will perform a traditional hard disk install of your running system, detects your file system layout and generates {{Path|/etc/fstab}} and installs a [[Bootloaders|bootloader]] based on the <Code>BOOTLOADER</Code> [[Alpine_setup_scripts#Environment_Variables|environment variable]].
# At the end of Installation, you can [[Installation#Reboot|reboot]] to boot into the newly installed Alpine Linux and [[Installation#Post-Installation|configure]] further.

== Troubleshooting ==

=== Mounting on /dev/sdXY sysroot failed ===

The error message appears as follows with variations in <code>/dev/sda8</code> depending on the partition number and SSD/HDD etc:

<Pre>
mounting /dev/sda8 on /sysroot failed: No such file or directory
mounting root: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot
sh: can't access tty: job control turned off
</Pre>

The above error message can be caused by various reasons. Follow the below steps in the emergency shell to identify one possible cause.

# Verify that the partition name in which Alpine Linux was installed matches the above [[#Mounting on /dev/sdXY sysroot failed|error]] by issuing the command and also note down the filesystem type of that partition (say TYPE="ext4") : {{Cmd| blkid}}
# If the expected disk (e.g., /dev/sda, /dev/nvme0n1) itself is missing in the output of {{ic| blkid}}, check [[#Disks not detected after setup-disk|Disks not detected after setup-disk]].
# Verify that sysroot exists by issuing the command. {{Cmd|ls -ld /sysroot}}
# Check if the above error message apears when issuing the command. {{Cmd|mount /dev/sda8 /sysroot}}
# If there is no error message, proceed to check if the issue is caused by a [[#Filesystem corruption|filesystem corruption]].
# If the manual mount command fails with "No such file or directory" even though you verified /sysroot exists in Step 3, this confirms the kernel doesn't recognize the filesystem type. Check whether filesystem modules(change ext4 if needed) are loaded by issuing the command. {{Cmd|<nowiki>lsmod | grep ext4 </nowiki>}}
# If there is no output, then it confirms that the above [[#Mounting on /dev/sdXY sysroot failed|issue]] is caused by [[#Missing filesystem modules in the kernel cmdline|missing filesystem module]].

==== Disks not detected after setup-disk====

After running the standard Alpine installation command: {{ic|setup-disk -m sys /mnt}} and rebooting, the system gives the error mentioned in [[#Mounting on /dev/sdXY sysroot failed|Mounting on /dev/sdXY sysroot failed]] with the expected disk (e.g., /dev/sda, /dev/nvme0n1) missing to show at the output of {{ic| blkid}}. This prevents booting into the installed system.

Issue: As per [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10615 bug report] this might be caused by BIOS storage controller being set to "RAID On (Intel Rapid Storage Technology)".

Resolution: Switch the storage mode in BIOS/UEFI: Go to BIOS → Storage or SATA/NVMe Operation. Change setting from:RAID On (Intel Rapid Storage Technology) to: AHCI or AHCI/NVMe.

==== Missing filesystem modules in the kernel cmdline ====

[[BusyBox]] mount command does not autoload modules, so need to add filesystem modules to the kernel cmdline. Even though alpine installer does this automatically, this has to be taken care of in case of manual disk install, particularly for [[Dualbooting|dualboot]] installations.

# To resolve, issue the command to load the appropriate filesystem module(say TYPE="ext4").{{Cmd|modprobe ext4}}
# To verify if the issue is resolved, reissue the command.{{Cmd|mount /dev/sda8 /sysroot}}
# If mount succeeded, issue the following command to boot into Alpine Linux. {{Cmd|exit}}

Choose the appropriate solution based on your use case for a permanent fix:

*If you are using [[Bootloaders#GRUB|grub]], then ensure that {{Codeline|GRUB_CMDLINE_LINUX}} line in the file {{Path|/etc/default/grub}} has the appropriate filesystem module <code>ext4</code> and <code>rootfstype=ext4</code> as follows: {{Cat|/etc/default/grub|<nowiki>...
GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4"
...</nowiki>}}

* If you are using [[Bootloaders#Syslinux|ExtLinux/SysLinux]], then ensure that {{Codeline|APPEND}} line in the file {{Path|/boot/extlinux.conf}} has <code>root=UUID=<UUID ID></code> or <code>root=/dev/sdXY</code> and the same matches the root path in the {{Path|/etc/fstab}} file. Also ensure that modules has the appropriate filesystem like <code>ext4</code> as follows: {{Cat|/boot/extlinux.conf|<nowiki>...
APPEND root=/dev/sdXY modules=sd-mod,usb-storage,ext4 quiet
# root=UUID=<UUID ID> can be used also in the APPEND Line.
...</nowiki>}}

{{Note|For both above cases, you may need to issue {{Codeline|update-grub}} or {{Codeline|update-extlinux}} after making above changes.}}

*For a solution independent of [[Bootloaders|bootloaders]], ensure that the file {{Path|/etc/mkinitfs/mkinitfs.conf}} has the necessary filesystem module in it. Refer [[Initramfs init|Initramfs]] page for more information and recreate initramfs image.

==== Filesystem corruption ====

To fix filesystem corruption issues, the command fsck must be run on the root partition. The root partition should be umounted before running fsck. Boot from a [[Rescue disk]] to run the fsck command on the root partition:{{Cmd|<nowiki># fsck -y /dev/<DEVICE></nowiki>}}

After running fsck, proceed to Reboot the Computer.

If the fsck Command does Fix the Corruption on the Root File System but the '''Error: Mounting Root Failed''' still persists then the next step would be to ReBuild the '''initramfs''' File System with the '''mkinitfs''' Command then Reboot. You need to '''Mount the Root Partition''' and [[Chroot]] into the Mounted Root Partition before running the mkinitfs Command as shown in the [[Initramfs init|initramfs]] page.

==== Check File System Kernel Modules are Loading ====

{{Cmd|<nowiki># lsmod | grep <File System></nowiki>}}
{{Note |<nowiki>File System = EXT2, EXT3, EXT4, BTRFS, XFS, FAT</nowiki>|}}

* Run the Command to Output the File System Kernel Modules:

{{Cat |Console Ouput|<nowiki>
alpinepc:~# lsmod | grep ext4

ext4 1155072 2
crc16 12288 1 ext4
mbcache 16384 1 ext4
jbd2 200704 1 ext4
</nowiki>}}
EXT4 = File System 
CRC16 = EXT4 Compression Support 
MBCACHE = MetaData Cache 
JBD2 = Journaling 

=== Blinking underscore ===

On a UEFI system, at the end of Installation after rebooting, the computer screen may appear with a '''blinking underscore'''. This may be due to the firmware not finding a valid boot entry.

The [[UEFI#EFI bootloaders|EFI bootloader]] entries are added without writing to NVRAM, thus preventing GRUB from calling {{ic|efibootmgr}}. In some cases the UEFI firmware may not boot from a bootloader without a valid NVRAM entry. In such cases, at the end of installation, instead of rebooting, manually add an entry for Alpine Linux in the NVRAM as follows:
* Install the {{pkg|efibootmgr}} package:{{Cmd|# apk add efibootmgr}}
* Adjust the device name {{ic|/dev/sdX}} and partition number {{ic|1}}, before issuing the command: {{Cmd|# efibootmgr --create --disk /dev/sdX --part 1 --label "Alpine" --loader '\EFI\alpine\grubx64.efi'}}

== See also ==

* [[Bootloaders]] - For information on GRUB, Syslinux and rEFInd
* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
* [[Installing Alpine Linux in a chroot|Installing Alpine Linux in a chroot]]
* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]

[[Category:Installation]]

System Disk Mode

2026-02-11T00:38:19Z

Kenrmayfield:

System Disk mode is the traditional or classic harddisk installation of Alpine Linux. This installation mode is suitable for most use cases including generic [[Tutorials_and_Howtos#Desktop|desktop]], [[Setting up the build environment|development machine]] etc.

If an entire hard disk(s) is available for Alpine Linux, [[Installation#setup-alpine_based_System_Disk_Install|setup-alpine based install]] is the recommended way to install Alpine Linux. For all other use cases, follow the [[Alpine_setup_scripts#setup-disk|<code>setup-disk</code>]] based Installation given below.

== setup-disk based Installation ==

To perform a traditional hard-disk installation of Alpine Linux, after completing the base configuration, proceed to create, format and mount your partitions with MOUNTPOINT {{Path|'''/mnt'''}} as root and run the command {{Codeline|'''<Code>setup-disk -m sys /mnt</Code>'''}}.

# Follow the [[Installation#General_course_of_action|Installation guide]] to complete the [[Installation#Base_configuration|base configuration]], if not already done. A working [[Configure_Networking#Connectivity_testing|Internet access]] is mandatory to complete this installation.
# If necessary formatted partition(s) are unavailable, manually [[Setting up disks manually#Creating_partitions|create]] them first and [[Setting up disks manually#Formatting_partitions|format]] them including swap partition(if used). If you're using legacy BIOS mode, use DOS i.e MBR partition table and ensure that proper partition is bootable for [[Bootloaders#Syslinux|extlinux]].
# Mount the '''/ (root)''' partition on a mount point i.e say {{Path|/mnt}} as follows: {{Cmd|# mount /dev/sdXY /mnt}}
# If you're using [[UEFI|EFI]], create a mount point <code>/mnt/boot</code> and mount the EFI system partition(ESP) on it. {{Cmd|<nowiki># mkdir -p /mnt/boot
# mount /dev/sdXY /mnt/boot</nowiki>}}
# If [[Swap|swap]] partition is available, you can also enable it now: {{Cmd|# swapon /dev/sdXY }}
# Install Alpine Linux using the following command: {{Cmd|# setup-disk -m sys /mnt}}
# <code>setup-disk</code> will perform a traditional hard disk install of your running system, detects your file system layout and generates {{Path|/etc/fstab}} and installs a [[Bootloaders|bootloader]] based on the <Code>BOOTLOADER</Code> [[Alpine_setup_scripts#Environment_Variables|environment variable]].
# At the end of Installation, you can [[Installation#Reboot|reboot]] to boot into the newly installed Alpine Linux and [[Installation#Post-Installation|configure]] further.

== Troubleshooting ==

=== Mounting on /dev/sdXY sysroot failed ===

The error message appears as follows with variations in <code>/dev/sda8</code> depending on the partition number and SSD/HDD etc:

<Pre>
mounting /dev/sda8 on /sysroot failed: No such file or directory
mounting root: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot
sh: can't access tty: job control turned off
</Pre>

The above error message can be caused by various reasons. Follow the below steps in the emergency shell to identify one possible cause.

# Verify that the partition name in which Alpine Linux was installed matches the above [[#Mounting on /dev/sdXY sysroot failed|error]] by issuing the command and also note down the filesystem type of that partition (say TYPE="ext4") : {{Cmd| blkid}}
# If the expected disk (e.g., /dev/sda, /dev/nvme0n1) itself is missing in the output of {{ic| blkid}}, check [[#Disks not detected after setup-disk|Disks not detected after setup-disk]].
# Verify that sysroot exists by issuing the command. {{Cmd|ls -ld /sysroot}}
# Check if the above error message apears when issuing the command. {{Cmd|mount /dev/sda8 /sysroot}}
# If there is no error message, proceed to check if the issue is caused by a [[#Filesystem corruption|filesystem corruption]].
# If the manual mount command fails with "No such file or directory" even though you verified /sysroot exists in Step 3, this confirms the kernel doesn't recognize the filesystem type. Check whether filesystem modules(change ext4 if needed) are loaded by issuing the command. {{Cmd|<nowiki>lsmod | grep ext4 </nowiki>}}
# If there is no output, then it confirms that the above [[#Mounting on /dev/sdXY sysroot failed|issue]] is caused by [[#Missing filesystem modules in the kernel cmdline|missing filesystem module]].

==== Disks not detected after setup-disk====

After running the standard Alpine installation command: {{ic|setup-disk -m sys /mnt}} and rebooting, the system gives the error mentioned in [[#Mounting on /dev/sdXY sysroot failed|Mounting on /dev/sdXY sysroot failed]] with the expected disk (e.g., /dev/sda, /dev/nvme0n1) missing to show at the output of {{ic| blkid}}. This prevents booting into the installed system.

Issue: As per [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10615 bug report] this might be caused by BIOS storage controller being set to "RAID On (Intel Rapid Storage Technology)".

Resolution: Switch the storage mode in BIOS/UEFI: Go to BIOS → Storage or SATA/NVMe Operation. Change setting from:RAID On (Intel Rapid Storage Technology) to: AHCI or AHCI/NVMe.

==== Missing filesystem modules in the kernel cmdline ====

[[BusyBox]] mount command does not autoload modules, so need to add filesystem modules to the kernel cmdline. Even though alpine installer does this automatically, this has to be taken care of in case of manual disk install, particularly for [[Dualbooting|dualboot]] installations.

# To resolve, issue the command to load the appropriate filesystem module(say TYPE="ext4").{{Cmd|modprobe ext4}}
# To verify if the issue is resolved, reissue the command.{{Cmd|mount /dev/sda8 /sysroot}}
# If mount succeeded, issue the following command to boot into Alpine Linux. {{Cmd|exit}}

Choose the appropriate solution based on your use case for a permanent fix:

*If you are using [[Bootloaders#GRUB|grub]], then ensure that {{Codeline|GRUB_CMDLINE_LINUX}} line in the file {{Path|/etc/default/grub}} has the appropriate filesystem module <code>ext4</code> and <code>rootfstype=ext4</code> as follows: {{Cat|/etc/default/grub|<nowiki>...
GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4"
...</nowiki>}}

* If you are using [[Bootloaders#Syslinux|ExtLinux/SysLinux]], then ensure that {{Codeline|APPEND}} line in the file {{Path|/boot/extlinux.conf}} has <code>root=UUID=<UUID ID></code> or <code>root=/dev/sdXY</code> and the same matches the root path in the {{Path|/etc/fstab}} file. Also ensure that modules has the appropriate filesystem like <code>ext4</code> as follows: {{Cat|/boot/extlinux.conf|<nowiki>...
APPEND root=/dev/sdXY modules=sd-mod,usb-storage,ext4 quiet
# root=UUID=<UUID ID> can be used also in the APPEND Line.
...</nowiki>}}

{{Note|For both above cases, you may need to issue {{Codeline|update-grub}} or {{Codeline|update-extlinux}} after making above changes.}}

*For a solution independent of [[Bootloaders|bootloaders]], ensure that the file {{Path|/etc/mkinitfs/mkinitfs.conf}} has the necessary filesystem module in it. Refer [[Initramfs init|Initramfs]] page for more information and recreate initramfs image.

==== Filesystem corruption ====

To fix filesystem corruption issues, the command fsck must be run on the root partition. The root partition should be umounted before running fsck. Boot from a [[Rescue disk]] to run the fsck command on the root partition:{{Cmd|<nowiki># fsck -y /dev/<DEVICE></nowiki>}}

After running fsck, proceed to Reboot the Computer.

If the fsck Command does Fix the Corruption on the Root File System but the '''Error: Mounting Root Failed''' still persists then the next step would be to ReBuild the '''initramfs''' File System with the '''mkinitfs''' Command then Reboot. You need to '''Mount the Root Partition''' and [[Chroot]] into the Mounted Root Partition before running the mkinitfs Command as shown in the [[Initramfs init|initramfs]] page.

==== Check File System Kernel Modules are Loading ====

{{Cmd|<nowiki># lsmod | grep <File System></nowiki>}}

* Run the Command to Output the File System Kernel Modules:

{{Cat |Console Ouput|<nowiki>
alpinepc:~# lsmod | grep ext4

ext4 1155072 2
crc16 12288 1 ext4
mbcache 16384 1 ext4
jbd2 200704 1 ext4
</nowiki>}}
EXT4 = File System 
CRC16 = EXT4 Compression Support 
MBCACHE = MetaData Cache 
JBD2 = Journaling 

=== Blinking underscore ===

On a UEFI system, at the end of Installation after rebooting, the computer screen may appear with a '''blinking underscore'''. This may be due to the firmware not finding a valid boot entry.

The [[UEFI#EFI bootloaders|EFI bootloader]] entries are added without writing to NVRAM, thus preventing GRUB from calling {{ic|efibootmgr}}. In some cases the UEFI firmware may not boot from a bootloader without a valid NVRAM entry. In such cases, at the end of installation, instead of rebooting, manually add an entry for Alpine Linux in the NVRAM as follows:
* Install the {{pkg|efibootmgr}} package:{{Cmd|# apk add efibootmgr}}
* Adjust the device name {{ic|/dev/sdX}} and partition number {{ic|1}}, before issuing the command: {{Cmd|# efibootmgr --create --disk /dev/sdX --part 1 --label "Alpine" --loader '\EFI\alpine\grubx64.efi'}}

== See also ==

* [[Bootloaders]] - For information on GRUB, Syslinux and rEFInd
* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
* [[Installing Alpine Linux in a chroot|Installing Alpine Linux in a chroot]]
* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]

[[Category:Installation]]

System Disk Mode

2026-02-10T23:22:47Z

Kenrmayfield:

System Disk mode is the traditional or classic harddisk installation of Alpine Linux. This installation mode is suitable for most use cases including generic [[Tutorials_and_Howtos#Desktop|desktop]], [[Setting up the build environment|development machine]] etc.

If an entire hard disk(s) is available for Alpine Linux, [[Installation#setup-alpine_based_System_Disk_Install|setup-alpine based install]] is the recommended way to install Alpine Linux. For all other use cases, follow the [[Alpine_setup_scripts#setup-disk|<code>setup-disk</code>]] based Installation given below.

== setup-disk based Installation ==

To perform a traditional hard-disk installation of Alpine Linux, after completing the base configuration, proceed to create, format and mount your partitions with MOUNTPOINT {{Path|'''/mnt'''}} as root and run the command {{Codeline|'''<Code>setup-disk -m sys /mnt</Code>'''}}.

# Follow the [[Installation#General_course_of_action|Installation guide]] to complete the [[Installation#Base_configuration|base configuration]], if not already done. A working [[Configure_Networking#Connectivity_testing|Internet access]] is mandatory to complete this installation.
# If necessary formatted partition(s) are unavailable, manually [[Setting up disks manually#Creating_partitions|create]] them first and [[Setting up disks manually#Formatting_partitions|format]] them including swap partition(if used). If you're using legacy BIOS mode, use DOS i.e MBR partition table and ensure that proper partition is bootable for [[Bootloaders#Syslinux|extlinux]].
# Mount the '''/ (root)''' partition on a mount point i.e say {{Path|/mnt}} as follows: {{Cmd|# mount /dev/sdXY /mnt}}
# If you're using [[UEFI|EFI]], create a mount point <code>/mnt/boot</code> and mount the EFI system partition(ESP) on it. {{Cmd|<nowiki># mkdir -p /mnt/boot
# mount /dev/sdXY /mnt/boot</nowiki>}}
# If [[Swap|swap]] partition is available, you can also enable it now: {{Cmd|# swapon /dev/sdXY }}
# Install Alpine Linux using the following command: {{Cmd|# setup-disk -m sys /mnt}}
# <code>setup-disk</code> will perform a traditional hard disk install of your running system, detects your file system layout and generates {{Path|/etc/fstab}} and installs a [[Bootloaders|bootloader]] based on the <Code>BOOTLOADER</Code> [[Alpine_setup_scripts#Environment_Variables|environment variable]].
# At the end of Installation, you can [[Installation#Reboot|reboot]] to boot into the newly installed Alpine Linux and [[Installation#Post-Installation|configure]] further.

== Troubleshooting ==

=== Mounting on /dev/sdXY sysroot failed ===

The error message appears as follows with variations in <code>/dev/sda8</code> depending on the partition number and SSD/HDD etc:

<Pre>
mounting /dev/sda8 on /sysroot failed: No such file or directory
mounting root: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot
sh: can't access tty: job control turned off
</Pre>

The above error message can be caused by various reasons. Follow the below steps in the emergency shell to identify one possible cause.

# Verify that the partition name in which Alpine Linux was installed matches the above [[#Mounting on /dev/sdXY sysroot failed|error]] by issuing the command and also note down the filesystem type of that partition (say TYPE="ext4") : {{Cmd| blkid}}
# If the expected disk (e.g., /dev/sda, /dev/nvme0n1) itself is missing in the output of {{ic| blkid}}, check [[#Disks not detected after setup-disk|Disks not detected after setup-disk]].
# Verify that sysroot exists by issuing the command. {{Cmd|ls -ld /sysroot}}
# Check if the above error message apears when issuing the command. {{Cmd|mount /dev/sda8 /sysroot}}
# If there is no error message, proceed to check if the issue is caused by a [[#Filesystem corruption|filesystem corruption]].
# If the manual mount command fails with "No such file or directory" even though you verified /sysroot exists in Step 3, this confirms the kernel doesn't recognize the filesystem type. Check whether filesystem modules(change ext4 if needed) are loaded by issuing the command. {{Cmd|<nowiki>lsmod | grep ext4 </nowiki>}}
# If there is no output, then it confirms that the above [[#Mounting on /dev/sdXY sysroot failed|issue]] is caused by [[#Missing filesystem modules in the kernel cmdline|missing filesystem module]].

==== Disks not detected after setup-disk====

After running the standard Alpine installation command: {{ic|setup-disk -m sys /mnt}} and rebooting, the system gives the error mentioned in [[#Mounting on /dev/sdXY sysroot failed|Mounting on /dev/sdXY sysroot failed]] with the expected disk (e.g., /dev/sda, /dev/nvme0n1) missing to show at the output of {{ic| blkid}}. This prevents booting into the installed system.

Issue: As per [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10615 bug report] this might be caused by BIOS storage controller being set to "RAID On (Intel Rapid Storage Technology)".

Resolution: Switch the storage mode in BIOS/UEFI: Go to BIOS → Storage or SATA/NVMe Operation. Change setting from:RAID On (Intel Rapid Storage Technology) to: AHCI or AHCI/NVMe.

==== Missing filesystem modules in the kernel cmdline ====

[[BusyBox]] mount command does not autoload modules, so need to add filesystem modules to the kernel cmdline. Even though alpine installer does this automatically, this has to be taken care of in case of manual disk install, particularly for [[Dualbooting|dualboot]] installations.

# To resolve, issue the command to load the appropriate filesystem module(say TYPE="ext4").{{Cmd|modprobe ext4}}
# To verify if the issue is resolved, reissue the command.{{Cmd|mount /dev/sda8 /sysroot}}
# If mount succeeded, issue the following command to boot into Alpine Linux. {{Cmd|exit}}

Choose the appropriate solution based on your use case for a permanent fix:

*If you are using [[Bootloaders#GRUB|grub]], then ensure that {{Codeline|GRUB_CMDLINE_LINUX}} line in the file {{Path|/etc/default/grub}} has the appropriate filesystem module <code>ext4</code> and <code>rootfstype=ext4</code> as follows: {{Cat|/etc/default/grub|<nowiki>...
GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4"
...</nowiki>}}

* If you are using [[Bootloaders#Syslinux|ExtLinux/SysLinux]], then ensure that {{Codeline|APPEND}} line in the file {{Path|/boot/extlinux.conf}} has <code>root=UUID=<UUID ID></code> or <code>root=/dev/sdXY</code> and the same matches the root path in the {{Path|/etc/fstab}} file. Also ensure that modules has the appropriate filesystem like <code>ext4</code> as follows: {{Cat|/boot/extlinux.conf|<nowiki>...
APPEND root=/dev/sdXY modules=sd-mod,usb-storage,ext4 quiet
# root=UUID=<UUID ID> can be used also in the APPEND Line.
...</nowiki>}}

{{Note|For both above cases, you may need to issue {{Codeline|update-grub}} or {{Codeline|update-extlinux}} after making above changes.}}

*For a solution independent of [[Bootloaders|bootloaders]], ensure that the file {{Path|/etc/mkinitfs/mkinitfs.conf}} has the necessary filesystem module in it. Refer [[Initramfs init|Initramfs]] page for more information and recreate initramfs image.

==== Filesystem corruption ====

To fix filesystem corruption issues, the command fsck must be run on the root partition. The root partition should be umounted before running fsck. Boot from a [[Rescue disk]] to run the fsck command on the root partition:{{Cmd|<nowiki># fsck -y /dev/<DEVICE></nowiki>}}

After running fsck, proceed to Reboot the Computer.

If the fsck Command does Fix the Corruption on the Root File System but the '''Error: Mounting Root Failed''' still persists then the next step would be to ReBuild the '''initramfs''' File System with the '''mkinitfs''' Command then Reboot. You need to '''Mount the Root Partition''' and [[Chroot]] into the Mounted Root Partition before running the mkinitfs Command as shown in the [[Initramfs init|initramfs]] page.

=== Blinking underscore ===

On a UEFI system, at the end of Installation after rebooting, the computer screen may appear with a '''blinking underscore'''. This may be due to the firmware not finding a valid boot entry.

The [[UEFI#EFI bootloaders|EFI bootloader]] entries are added without writing to NVRAM, thus preventing GRUB from calling {{ic|efibootmgr}}. In some cases the UEFI firmware may not boot from a bootloader without a valid NVRAM entry. In such cases, at the end of installation, instead of rebooting, manually add an entry for Alpine Linux in the NVRAM as follows:
* Install the {{pkg|efibootmgr}} package:{{Cmd|# apk add efibootmgr}}
* Adjust the device name {{ic|/dev/sdX}} and partition number {{ic|1}}, before issuing the command: {{Cmd|# efibootmgr --create --disk /dev/sdX --part 1 --label "Alpine" --loader '\EFI\alpine\grubx64.efi'}}

== See also ==

* [[Bootloaders]] - For information on GRUB, Syslinux and rEFInd
* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
* [[Installing Alpine Linux in a chroot|Installing Alpine Linux in a chroot]]
* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]

[[Category:Installation]]

Bootloaders

2026-02-10T23:12:46Z

Kenrmayfield:

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 
* <code>[[#rEFInd|rEFInd]]</code> is an easy-to-use ''EFI'' boot menu that allows booting different operating systems. 
* <code>[[#GRUB|GRUB]]</code> is a standard Linux bootloader used in Alpine Linux when Installing the Alpine OS to Disk via UEFI. 
* <code>[[#EFI_Boot_Stub|EFI Boot Stub]]</code> allows for booting Linux directly from a motherboard supporting ''UEFI'' or from another bootloader. 
* [[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>

== rEFInd ==
{{Main|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:

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

== 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/}}. }}

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