Setting up disks manually

Alpine Linux modes

Alpine Linux can be installed and run in following three modes.

Diskless Mode

In Diskless mode the entire operating system with all applications are first loaded into RAM and then only run from there. This is the method already used to boot the .iso installation images, however setup-alpine can also configure the installed system to continue to boot like this if "disk=none" is specified. The mode is extremely fast and can save on unnecessary disk spin-ups, power, and wear. It is similar to what other linux distributions may call a "frugal" install or boot into with a "toram" option.

Custom configurations and package installations may optionally still be preserved or "persist" across reboots by using the Alpine local backup tool lbu. It enables committing and reverting system states by using .apkovl files that are saved to writable storage and loaded when booting. If additional or updated packages have been added to the system, these may also be made available for automatic (re)installation during the boot phase without any (re)downloading, by enabling a local package cache on the writable storage.

[FIXME-1: Storing local configs and the package cache on internal disks still require some manual steps to have the partition listed, i.e. making a /etc/fstab entry, mountpoint, and mount, *before* running setup-alpine. The linked workaround also still requires to commit these configurations to disk manually before rebooting.]

If a writable partition is available, setup-alpine can be told to store the configs and the package cache on that writable partition. (Later, another directory on that same partition or another available partition may also be mounted as /home, or for example, for selected important applications to keep their run-time and user data on it.)

The boot device of the newly configured local "diskless" system may remain the initial (and possibly read-only) installation media. But it is also possible to copy the boot system to a partition (e.g. /dev/sdXY) with setup-bootable.

Data Disk Mode

In Data Disk mode also the operating system runs from system RAM, thus it enjoys the same accelerated operation speed as "diskless" mode. However, swap storage and the entire /var directory tree get mounted from a persistent storage device (two newly created partitions). The directory /var holds e.g. all log files, mailspools, databases, etc., as well as lbu backup commits and the package cache. This mode is useful for having RAM accelerated servers with variable amounts of user-data that exceed the available RAM size. It enables the entire current system state (not just the boot state) to survive a system crash in accordance with the particular filesystem guarantees.

[FIXME-2]: Setup-alpine will create the data partition and mount it as /var, but setup-alpine's "data" disk mode can not yet configure lbu config storage settings automatically. The current workaround, is to select "none" at the 'where to store configs' prompt (as the new data partition is not listed anyway) and configure lbu manually after setup-alpine exits, and before rebooting:

1. Identify the created data partition, e.g. /dev/sdXY, and its filesystemtype, e.g. using lsblk
2. Manually edit the lbu backups location in /etc/lbu/lbu.conf and configure LBU_MEDIA=sdXY (according to the previous findings).
3. Save the configuration on that partition for the next boot with lbu commit.
4. If (a new) partition fails to get mounted, execute: mkdir /media/sdXY ; echo "/dev/sdXY /media/sdXY fstype noauto,rw 0 0" >> /etc/fstab, and try lbu commit again.

In data disk mode, the boot device may also remain the initial (and possibly read-only) installation media, or be copied to a partition (e.g. /dev/sdXY) with setup-bootable.

System Disk Mode

System Disk Mode is the traditional hard-disk install. If this mode is selected, the setup-alpine script deletes the existing partitions and creates three partitions on the selected storage device, /boot, swap and / (the filesystem root). This mode may, for example, be used for generic desktop and development machines.

Refer #Custom partitioning of the harddisk, if you do not want to use entire disk for Alpine Linux. The menu choices that are provided by setup-alpine might not cover all needs, however, it's possible to:

• Call setup-disk directly, instead of through setup-alpine, and pass some specific partitioning parameters to it.
• Set up the partitions and filesystems manually (to the desired details) and tell setup-disk to install to the prepared target mountpoint.

(Beta reference: docs.alpinelinux.org )

Using setup-alpine (setup-disk) features

For "diskless" and "data" disk mode installs

This requires some manual steps, as long as the setup-scripts auto-detect usable partitions only on removable devices (not internal harddisks). They do not support creating new, writable partitions to be used by Alpine.

How to prepare writable storage space is explained in the section manual partitioning, below.

For "sys" disk mode installs

This material is work-in-progress ... Some information on this page may be incomplete or outdate. (Last edited by Prabuanand on 12 Sep 2024.)

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

Todo: Does adding the --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

Todo: Does adding the --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

Todo: Does adding the --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.

Manual partitioning

Partitioning tools

The installation image enviroment may have only the very basic busybox built-in fdisk command available. However, 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).

The following steps installs cfdisk, looks for existing partitions, and runs cfdisk against /dev/sdX:

# apk add cfdisk e2fsprogs

# blkid

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

# cfdisk /dev/sdX

For "diskless" and "data" disk mode installs

• Be aware of this Bug: #11589. The APKOVL loading of diskless setups doesn't work on btrfs and xfs filesystems, or nvme-based devices => So, for the moment, use only ext4 filesystem partitions on classic drives to store diskless mode states.

The following creates an ext4 partition with disabled journaling, to reduce write operations and allow the disk to spin down after the .apkovl and the packages have been read from the partition during the boot.

# mkfs.ext4 -O ^has_journal /dev/sdXY   # the "-O ^has_journal" DISABLES journaling ("^" means "not")

Note: IMPORTANT! There may be additional steps necessary to make proper use of the partition, see

Saving and loading ISO image customizations.

Note: mkfs.ext4 creates ext4 fs with 64bit feature enabled by default, but extlinux may not be able to boot with that, see Issue #14895. You may need to add "-O ^has_journal,^64bit" to mkfs.ext4 to circumvent this.

For "sys" disk mode installs

setup-disk will by default set up a root partition, a separate /boot partition and a swap partition. If you want a different layout, you can manually create the partitions, filesystems and mount them on /mnt (or any other mount point) then run:

setup-disk /mnt

setup-disk will install your running system on the mounted root, detect your file system layout and generate an fstab.

If you're using the MBR, you are responsible for making the proper partition bootable and make sure the MBR is OK for extlinux. If you're going to use EFI, make sure you mount esp partition on /boot/efi and set BOOTLOADER=grub and USE_EFI=1, and that grub-efi and efibootmgr are installed before running setup-disk. If your system still does not boot, you can try to manually create a boot entry with efibootmgr, for which instructions can be found at EFI Boot Stub.

See also setup-partitions

Dual-booting

See Install to HDD with dual-boot

Other needs

• Installing Alpine Linux in a chroot
• Replacing non-Alpine Linux with Alpine remotely

Setting up swap

1. create a partition with the type set to "linux swap" (82) (If you're going to use a logical volume for swap, skip this step and lvcreate that instead.)
2. mkswap /dev/sda2
3. echo -e "/dev/sda2 none swap sw 0 0" >> /mnt/etc/fstab
4. swapon /dev/sda2 (or rc-service swap start)

free -m

will show how much swap space is available (in MB).

If you prefer maximum speed, you don't need configure any raid devices for swap. Just add 2 swap partitions on different disks and linux will stripe them automatically. The downside is that the moment one disk fails, the system will go down. For better reliability, put swap on RAID1.

Todo: Instructions for cryptswap?

Custom boot partition size

The default boot partition size is under 40MB. This can cause errors if package updates require additional space on /boot. Executing export BOOT_SIZE=512 before running setup-disk will result in a 512MB boot partition.

Expanding an existing disk

Unlike gnu `fdisk`, busybox `fdisk` is rather limited in edit operations. Instead, use `cfdisk` and `resize2fs` to resize the disk. This can be done while booted.

Install tools:

cfdisk screenshot

# apk add cfdisk e2fsprogs-extra

resize disk

# cfdisk /dev/sda

1. Select the target partition, often /dev/sda3
2. Select Resize from the bottom menu
3. Select Write, then Quit

resize filesystem with -f (online mode), then reboot

# resize2fs -f /dev/sda3 # reboot