Setting up disks manually
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 machines 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 with basic to complex partitioning needs, complete the base configuration first. Then partition, format and mount your partitions on a MOUNTPOINT /mnt. Finally, run the command setup-disk -m sys /mnt to install Alpine Linux with /mnt as root.
- Follow the Installation guide to complete the base configuration, if not already done.
- If necessary formatted partition(s) are unavailable, manually create them first and format them with appropriate filesystem tools.
- Mount the / (root) partition on a mount point i.e say /mnt as follows:
# mount /dev/sdXY /mnt
- If you're using EFI, make sure you create a mount point
/mnt/boot.# mkdir -p /mnt/boot
- Find the correct partition name for
esppartition and mount it on the above mount point:# mount /dev/sdXY /mnt/boot
- If swap partition is available, you can also enable it now:
# swapon /dev/sdXY
- Install Alpine Linux using the following command:
# setup-disk -m sys /mnt
setup-diskwill 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 theBOOTLOADERenvironment variable.- At the end of Installation, you can reboot to boot into the newly installed Alpine Linux and configure further.
Manual partitioning
Partitioning tools
The installation image enviroment may have only the very basic busybox built-in fdisk command available. Busybox `fdisk` is rather limited for edit operations. Instead, alpine allows you to install more complete partitioning tool packages like sfdisk (scriptable fdisk), gptfdisk, parted (CLI), cfdisk (text menus), or even gparted (after setting up a graphical environment).
These tools can be installed even during Installation immediately after setting up base configuration.
Creating partitions
cfdisk will be used in all examples here as it is based on text menu without any dependencies. However, installing the package cfdisk requires network to be available if using Standard ISO boot image. Alternately, sfdisk is available and can be installed without network.
The following step installs the package cfdisk:
# apk add cfdisk
cfdisk will be used to create partitions. Before using cfdisk, 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
For Alpine Linux, only the (/)root partition is mandatory to. Even a /boot partition and swap are optional, when using
Resizing an existing partition
cfdisk and resize2fs 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
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. Commonly used formatting tools like mkfs.ext4, mkfs.vfat, mkfs.btrfs are part of file system tools dosfstools, e2fsprogs, btrfs-progs respectively. 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
# mkfs.vfat /dev/sdaXY
- f2fs-tools for F2FS filesystem
# mkfs.f2fs /dev/sdaXY
Disk layouts
 This entire section including RAID, Encryption and LVM needs to be updated. |
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
--update option to extlinux ... suffice to make /boot/extlinux.conf be regenerated? Or do we need to manually tweak that file, or run update-extlinux, as well?
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
See Setting up encrypted volumes with LUKS. 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
--update option to extlinux ... suffice to make /boot/extlinux.conf be regenerated? Or do we need to manually tweak that file, or run update-extlinux, as well?
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
--update option to extlinux ... suffice to make /boot/extlinux.conf be regenerated? Or do we need to manually tweak that file, or run update-extlinux, as well?
You might also need to manually tweak $MNT/etc/fstab.
Troubleshooting
mounting on sysroot failed
The error message appears as follows with variations in /dev/sdXY depending on the partition number and SSD/HDD etc:
mounting /dev/sdXY 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 different reasons. One possible cause and its resolution is given below:
Missing filesystem modules in the kernel cmdline
One possible Cause for the above issue is missing filesystem modules in the kernel cmdline. To confirm, follow the troubleshooting steps in the emergency shell and adjust ext4 with whatever is applicable to you:
- Issue the command
blkid and verify that partition in which Alpine Linux was installed appears and matches the one in the above error message.
- Note the partition type in the above
blkid output for the Alpine Linux partition. Say, for example: TYPE="ext4"
- Ensure that sysroot exists by issuing the command
ls -ld /sysroot.
- Issue the command
mount /dev/sda8 /sysroot and check if the error message matches # If the error message matches mount: mounting /dev/sdXY on /sysroot failed. No such file or directory.
- If yes, run
lsmod |grep ext4 to check whether filesystem modules are loaded. If there is no output, then issue the command modprobe ext4 to load the filesystem module.
- Reissue the command:
mount /dev/sda8 /sysroot. If mount succeeded, issue the command exit to boot into Alpine Linux.
Rootcause: 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.
For permanent fix, apply the applicable solution given below:
- 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 other bootloader, ensure that the file /etc/mkinitfs/mkinitfs.conf has the necessary filesystem modules in it. Refer Initramfs page for more information and recreate initramfs images, if required..
see also