System Disk Mode

System Disk mode is the traditional or classic harddisk installation of Alpine Linux. This installation mode is suitable for most use cases including generic desktop, development machine etc.

If an entire hard disk(s) is available for Alpine Linux, setup-alpine based install is the recommended way to install Alpine Linux. For all other use cases, follow the setup-disk 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 /mnt as root and run the command setup-disk -m sys /mnt.

1. Follow the Installation guide to complete the base configuration, if not already done. A working Internet access is mandatory to complete this installation.
2. If necessary formatted partition(s) are unavailable, manually create them first and 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 extlinux.
3. Mount the / (root) partition on a mount point i.e say /mnt as follows:

   # mount /dev/sdXY /mnt

4. If you're using EFI, create a mount point /mnt/boot and mount the EFI system partition(ESP) on it.

   # mkdir -p /mnt/boot # mount /dev/sdXY /mnt/boot

5. If swap partition is available, you can also enable it now:

   # swapon /dev/sdXY

6. Install Alpine Linux using the following command:

   # setup-disk -m sys /mnt

7. setup-disk will perform a traditional hard disk install of your running system, detects your file system layout and generates /etc/fstab and installs a bootloader based on the BOOTLOADER environment variable.
8. At the end of Installation, you can reboot to boot into the newly installed Alpine Linux and configure further.

Troubleshooting

Mounting on /dev/sdXY sysroot failed

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

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

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

1. Verify that the partition name in which Alpine Linux was installed matches the above error by issuing the command and also note down the filesystem type of that partition (say TYPE="ext4") :

   blkid

2. If the expected disk (e.g., /dev/sda, /dev/nvme0n1) itself is missing in the output of blkid, check Disks not detected after setup-disk.
3. Verify that sysroot exists by issuing the command.

   ls -ld /sysroot

4. Check if the above error message apears when issuing the command.

   mount /dev/sda8 /sysroot

5. If there is no error message, proceed to check if the issue is caused by a filesystem corruption.
6. 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.

   lsmod | grep ext4

7. If there is no output, then it confirms that the above issue is caused by missing filesystem module.

Disks not detected after setup-disk

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

Issue: As per 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 dualboot installations.

1. To resolve, issue the command to load the appropriate filesystem module(say TYPE="ext4").

   modprobe ext4

2. To verify if the issue is resolved, reissue the command.

   mount /dev/sda8 /sysroot

3. If mount succeeded, issue the following command to boot into Alpine Linux.

   exit

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

• If you are using grub, then ensure that GRUB_CMDLINE_LINUX line in the file /etc/default/grub has the appropriate filesystem module ext4 and rootfstype=ext4 as follows:

  Contents of /etc/default/grub

  ... GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4" ...

• If you are using ExtLinux/SysLinux, then ensure that APPEND line in the file /boot/extlinux.conf has root=UUID=<UUID ID> or root=/dev/sdXY and the same matches the root path in the /etc/fstab file. Also ensure that modules has the appropriate filesystem like ext4 as follows:

  Contents of /boot/extlinux.conf

  ... APPEND root=/dev/sdXY modules=sd-mod,usb-storage,ext4 quiet # root=UUID=<UUID ID> can be used also in the APPEND Line. ...

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

• For a solution independent of bootloaders, ensure that the file /etc/mkinitfs/mkinitfs.conf has the necessary filesystem module in it. Refer 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:

# fsck -y /dev/<DEVICE>

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 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 EFI bootloader entries are added without writing to NVRAM, thus preventing GRUB from calling 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 efibootmgr package:

  # apk add efibootmgr

• Adjust the device name /dev/sdX and partition number 1, before issuing the command:

  # efibootmgr --create --disk /dev/sdX --part 1 --label "Alpine" --loader '\EFI\alpine\grubx64.efi'

See also

• Bootloaders - For information on GRUB, Syslinux and rEFInd
• Install to HDD with dual-boot
• Installing Alpine Linux in a chroot
• setup-partitions