Setting up disks manually: Difference between revisions

Latest revision as of 15:23, 31 October 2025

Setting up disks manually involves creating partitions using partitioning tools and formatting such partitions using various filesystem utilities to allow System Disk Mode or traditional HDD Installation of Alpine Linux. In addition to the above information, this page also documents various Disk layouts involving RAID, Encryption and LVM.

Manual partitioning

setup-disk based Installation allows installing Alpine Linux on a partition after manually partitioning the HDD at the end of Base configuration step of Installation. However, the setup-alpine based System Disk Install requires and uses an entire HDD.

Partitioning tools

The installation image environment may have only the very basic busybox built-in fdisk command available. Instead, Alpine Linux allows you to install any of the below listed partitioning tool immediately after setting up base configuration.

Command	Package name	Features	Limitations
fdisk	Inbuilt busybox	can read GPT, Modify MBR	Cannot modify GPT
gdisk	gptfdisk	text mode, supports MBR/GPT bidirectional conversion, best for managing GPT partition tables	None
cgdisk	gptfdisk	menu driven curses interface for gdisk	None
sgdisk	sgdisk	scriptable gdisk	Non-interactive
fdisk	util-linux-misc	text mode, supports both gpt and MBR, best for managing MBR partition tables	None except size due to other tools
cfdisk	cfdisk	menu driven curses interface for fdisk	None
sfdisk	sfdisk	scriptable fdisk	Non-interactive
parted	parted	text mode, supports both gpt and MBR	cannot convert MBR to GPT, different interface from above tools

Graphical tools like gparted and gnome-disk-utility can be used only after setting up a graphical environment.

Creating partitions

For Alpine Linux, only the (/)root partition is mandatory. Even a /boot partition and swap are optional.

Warning: Make sure to choose the correct disk device in the below section. If you choose the wrong device, you will lose your data. Make a backup first and do not proceed, if you are unsure.

cfdisk will be used in all examples here as it is based on text menu without any dependencies. However, installing the cfdisk package requires network to be available if using Standard ISO boot image. Alternately, sfdisk can be installed without network.

Tip: Use cgdisk from gptfdisk package for GPT partitions and for conversion from MBR to GPT.

The following step installs the cfdisk package:

# apk add cfdisk

Before using cfdisk to create partitions, the disk name must be identified by using blkid:

# blkid

/dev/sdX1: LABEL="some" UUID="..." TYPE="vfat"
/dev/sdX2: LABEL="other" UUID="..." TYPE="ext4"

When cfdisk is run as follows, it looks for existing partitions on the disk /dev/sdX:

# cfdisk /dev/sdX

Resizing an existing partition

Warning: Make sure to choose the correct disk device in the below section. If you choose the wrong device, you will lose your data. Make a backup first and do not proceed, if you are unsure.

cfdisk and resize2fs from e2fsprogs-extra package can be used to resize existing partitions of ext2/3/4 filsystem on the disk. For other filsystems, the necessary filesystem tools must be installed. This can be done while booted.

To resize disk, launch the cfdisk:

# cfdisk /dev/sda

Select the target partition, here as per image /dev/sda3
Select Resize from the bottom menu.
Enter the new Size at the prompt.
Select Write, then Quit

If a filesystem is resized with -f (online mode), then the system must be rebooted immediately after the change is made.

# resize2fs -f /dev/sda3 # reboot

Formatting partitions

Warning: The /dev/sdXY is only an example. Make sure you use the right partition name/number. Use blkid command to verify the partition name/number. Choosing the wrong partition leads to data loss. If you are unsure, do not proceed, seek support.

Whenever a partition is created, the partition must be formatted first before using it. Depending on the filesystem to be used, the necessary formatting tool for the filesystem must be installed first.

Tool	Filesystem	Formatting command	Brief Notes
btrfs-progs	Btrfs	mkfs.btrfs	combines copy-on-write and volume management
dosfstools	FAT12/FAT16/FAT32	mkfs.vfat	also used for EFI partition
e2fsprogs	ext2/ext3/ext4	mkfs.ext4	ext4 is current default in Linux
exfatprogs	exfat	mkfs.exfat	Commonly used on USB flash drives and SD cards
f2fs-tools	F2FS	mkfs.f2fs
hfsprogs	HFS/HFS+	mkfs.hfsplus	Apple/Mac products
jfsutils	JFS	mkfs.jfs
ntfs-3g-progs	NTFS	mkfs.ntfs	Full-featured, Microsoft/Windows FUSE driver
squashfs-tools	SquashFS	mksquashfs	compressed read-only file system
xfsprogs	XFS	mkfs.xfs

Install the filesystem tools first, if not done already. The following examples show how to use the formatting tools for different filesystems:

e2fsprogs for ext4,ext3 and ext2. ext4 is the default filesystem in Alpine Linux:
# mkfs.ext4 /dev/sdaXY
btrfs-progs for btrfs filesystem.
# mkfs.btrfs /dev/sdaXY
dosfstools for fat12/fat16/fat32 filesystem. This is also used for EFI system partition(ESP).
# mkfs.vfat /dev/sdaXY
f2fs-tools for F2FS filesystem.
# mkfs.f2fs /dev/sdaXY

Disk layouts

It is possible to have one or more of RAID, encrypted, and/or Logical Volume on your / (root) volume. However, the Alpine init script only knows how to handle them when they're layered in that order, and your initram and extlinux.conf files in the /boot partition are configured properly.

Your /boot directory cannot reside on an encrypted or LVM volume, at least not with Alpine's default bootloader (extlinux). (Grub2 can deal with /boot being on an LVM volume.) The usual practice is to create a small partition for /boot, then devote the rest of your disk to a separate partition on which you layer one or more of RAID, encryption, and/or Logical Volumes.

Sometimes /boot is also set up as a mirrored (RAID1) volume. However, this is just for post-init access. That way, when you write a new kernel or bootloader config file to /boot, it gets written to multiple physical partitions. During the pre-init, bootloader phase, only one of those partitions will be read from.

A typical setup might look like this:

One-disk system
---------------
  +------------------------------------------------+
  |  small partition (32--100M), holding           |
  |  only /boot, filesystem needn't be journaled   |
  +------------------------------------------------+
  |  rest of disk in second partition              |
  |  +------------------------------------------+  |
  |  | cryptsetup volume                        |  |
  |  |  +-------------------------------------+ |  |
  |  |  |  LVM PV, containing single VG,      | |  |
  |  |  |  containing multiple LVs, holding   | |  |
  |  |  |  /, /home, swap, etc                | |  |
  |  |  +-------------------------------------+ |  |
  |  +------------------------------------------+  |
  +------------------------------------------------+


Two-disk system
---------------
  +------------------------------------------------+  +------------------------------------------------+
  |  small partition (32--100M), holding           |  |  small partition (32--100M), holding           | These 2 partitions might
  |  only /boot, filesystem needn't be journaled   |  |  only /boot, filesystem needn't be journaled   | form a mirrored (RAID1)
  +------------------------------------------------+  +------------------------------------------------+ volume
  |  rest of disk in second partition              |  |  rest of disk in second partition              |
  | T================================================================================================T | These 2 partitions form
  | T +--------------------------------------------------------------------------------------------+ T | a second mirrored
  | T | cryptsetup volume                                                                          | T | (RAID1) volume
  | T |  +---------------------------------------------------------------------------------------+ | T |
  | T |  | LVM PV, containing single VG,                                                         | | T |
  | T |  | containing multiple LVs, holding                                                      | | T |
  | T |  | /, /home, swap, etc                                                                   | | T |
  | T |  +---------------------------------------------------------------------------------------+ | T |
  | T +--------------------------------------------------------------------------------------------+ T |
  | T================================================================================================T |
  |                                                |  |                                                |
  +------------------------------------------------+  +------------------------------------------------+

In a three-disk system, the /boot would still be RAID1, but the larger partition might, in that case, be RAID5.

RAID

setup-disk will automatically build a RAID array if you supply the -r switch, or if you specify more than one device.

If you want to build your RAID array manually, see Setting up a software RAID array. Then you can add additional layers of encryption and/or Logical Volumes, or just assemble the RAID array, and supply the /dev/mdi device directly to setup-disk. When you're finished, be sure to disassemble the RAID array before rebooting.

If setup-disk sees that you're using RAID, either because you gave it the -r switch, or multiple devices, or a /dev/mdi device, then it will set up your initramfs and extlinux.conf file properly. However, in other cases, such as when you're also using encryption, or you invoke setup-disk with a mounted directory argument, these might not be properly set up for RAID. In that case, you may need to manually edit/rebuild them. The following assumes that $MNT holds the root directory you're installing into:

echo "/sbin/mdadm" > $MNT/etc/mkinitfs/files.d/raid echo "/etc/mdadm.conf" >> $MNT/etc/mkinitfs/files.d/raid # edit $MNT/etc/mkinitfs/mkinitfs.conf to make sure features="..." # includes raid (this field is space-separated and quoted) mkinitfs -c $MNT/etc/mkinitfs/mkinitfs.conf -b $MNT # edit $MNT/etc/update-extlinux.conf to make sure modules=... contains # raid1 or raid456 (whichever your / is on; this field is comma-separated) # also check the root= setting extlinux --raid --install $MNT/boot --update

You might also need to manually tweak $MNT/etc/fstab. And you might need to copy /usr/share/syslinux/mbr.bin to your disk's MBR.

Encryption

You can add an additional Logical Volume layer, or just unlock the volume you've created (using cryptsetup luksOpen ...), and supply the /dev/mapper/something device directly to setup-disk. When you're finished, be sure to relock the volume (using cryptsetup luksClose ...) before rebooting.

If you install your / (root) on an encrypted volume, you'll need to manually edit/rebuild your initram and your extlinux.conf file. The following assumes that $MNT holds the root directory you're installing into, that you've created the cryptvolume on the device /dev/md2, and that you want to unlock the encrypted volume into a virtual volume named "crypt":

# edit $MNT/etc/mkinitfs/mkinitfs.conf to make sure features="..." # includes cryptsetup (this field is space-separated and quoted) mkinitfs -c $MNT/etc/mkinitfs/mkinitfs.conf -b $MNT # edit $MNT/etc/update-extlinux.conf to make sure default_kernel_opts="..." # contains cryptroot=/dev/md1 and cryptdm=crypt (this field is also space-separated and quoted) # also check the root= setting extlinux --install $MNT/boot --update

You might also need to manually tweak $MNT/etc/fstab.

LVM

setup-disk will automatically build and use volumes in a LVM group if you supply the -L switch.

If you instead want to build your LVM system manually, see Setting up Logical Volumes with LVM. Then vgchange -ay, format and mount your volumes, and supply the root mountpoint to setup-disk. When you're finished, be sure to

umount ... vgchange -an

before rebooting.

If setup-disk sees that you're using LVM, perhaps because you gave it the -L switch, then it will set up your initram and extlinux.conf file properly. However, in other cases, these might not be properly set up. In that case, you may need to manually edit/rebuild them. The following assumes that $MNT holds the root directory you're installing into:

# edit $MNT/etc/mkinitfs/mkinitfs.conf to make sure features="..." # includes lvm (this field is space-separated and quoted) mkinitfs -c $MNT/etc/mkinitfs/mkinitfs.conf -b $MNT # edit $MNT/etc/update-extlinux.conf to make sure root= is set correctly extlinux --install $MNT/boot --update

You might also need to manually tweak $MNT/etc/fstab.

@@ Line 1: / Line 1: @@
-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.
+Setting up disks manually involves creating partitions using partitioning tools and formatting such partitions using various filesystem utilities to allow [[System Disk Mode]] or traditional HDD Installation of Alpine Linux. In addition to the above information, this page also documents various Disk layouts involving RAID, Encryption and LVM.
-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.
+== Manual partitioning ==
-== 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.
+[[System Disk Mode#setup-disk based Installation|setup-disk based Installation]] allows installing Alpine Linux on a partition after manually partitioning the HDD at the end of [[Installation#Base configuration|Base configuration step of Installation]]. However, the [[Installation#setup-alpine based System Disk Install|setup-alpine based System Disk Install]] requires and uses an entire HDD.
-# If necessary formatted partition(s) are unavailable, manually [[#Creating_partitions|create]] them first and [[#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 [[Filesystems#Swap_Partition|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.
-== Manual partitioning ==
+== Partitioning tools ==
-=== Partitioning tools ===
 The installation image environment may have only the very basic busybox built-in <code>fdisk</code> command available. Instead, Alpine Linux allows you to install any of the below listed partitioning tool immediately after setting up [[Installation#Base_configuration|base configuration]].
@@ Line 49: / Line 35: @@
 Graphical tools like {{pkg|gparted}} and {{pkg|gnome-disk-utility}} can be used only after [[Installation#Post-Installation|setting up a graphical environment]].
-=== Creating partitions ===
+== Creating partitions ==
 For Alpine Linux, only the '''(/)'''root partition is mandatory. Even  a '''/boot''' partition and  '''swap''' are optional.
@@ Line 68: / Line 54: @@
 When {{ic|cfdisk}} is run as follows, it looks for existing partitions on the disk {{Path|/dev/sdX}}: {{cmd|# cfdisk /dev/sdX}}
-=== Resizing an existing partition ===
+== Resizing an existing partition ==
 {{Warning|Make sure to choose the correct disk device in the below section. If you choose the wrong device, you will lose your data. Make a backup first and do not proceed, if you are unsure.}}
@@ Line 87: / Line 73: @@
 &num; reboot}}
-=== Formatting partitions ===
+== Formatting partitions ==
 {{Warning|The {{Path|/dev/sdXY}} is only an example. Make sure you use the right partition name/number. Use {{ic|blkid}} command to verify the partition name/number. Choosing the wrong partition leads to data loss. If you are unsure, do not proceed, seek [[Alpine Linux:Support|support]].}}
@@ Line 215: / Line 201: @@
 == 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]].
-# Ensure 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 the error message matched in step 4, check whether filesystem modules 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]].
-==== 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|Syslinux]], then ensure that {{Codeline|APPEND root}} line in the file {{Path|/boot/extlinux.conf}} has the appropriate filesystem module <code>ext4</code> as follows: {{Cat|/boot/extlinux.conf|<nowiki>...
-APPEND root=/dev/sdXY modules=sd-load,usb-storage,ext4 quiet
-...</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.
-==== 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/NVMeb.
-=== Blinking underscore ===
-On a UEFI system, at the end of Installation after rebooting, the computer screen appears with '''blinking underscore'''.
-Alpine Linux doesn't create entries in UEFI NVRAM and instead places the bootloader in {{Path|\EFI\alpine\grubx64.efi}} and the fallback boot path {{Path|\EFI\boot\bootx64.efi}}. However, some EFI firmware may fail to boot Alpine Linux from the fallback path. 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 command based on your device name {{ic|/dev/sdX}} and issue 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]]
-* [[Replacing non-Alpine Linux with Alpine remotely]]
-* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]
 * [https://www.rodsbooks.com/gdisk/index.html Gdisk official website] '' walkthroughs available for gdisk,cgdisk and sgdisk''
-[[Category:Installation]]
 [[Category:Storage]]