LVM on LUKS

Introduction

This documentation describes how to set up Alpine Linux using a logical volume (LV), that is installed in an encrypted partition. To encrypt the partition the logical volume manager (LVM) the volume group (VG) is installed in, the Device Mapper crypt (dm-crypt) module and Linux Unified Key Setup (LUKS) is used.

Note that you must install the /boot/ directory on an unecrypted partition to boot correctly.

Hard Disk Device Name

The following documentation uses the vda device as installation destination. If your environment uses a different device name for your hard disk, use the corresponding device names in the examples.

Setting up Alpine Linux Using LVM on Top of a LUKS Partition

To install Alpine Linux in logical volumes running on top of a LUKS encrypted partition, you cannot use the official installation procedure. The installation requires several manual steps you must run in the Alpine Linux Live CD environment.

Preparing the Temporary Installation Environment

Before you begin to install Alpine Linux, prepare the temporary environment:

Note: All settings in this section apply only to the temporary environment and not to the later installed Alpine Linux on your hard disk.

• Boot the latest Alpine Linux Installation CD.

• At the login prompt, use the root user without password to log in.

• Optionally, set the keyboard language:

# setup-keymap

The default keyboard mapping is us-us

• Configure the network interface:

# setup-interfaces

If you set a static IP address, additionally configure DNS be able to resolve host names:

# setup-dns

• Enable the network interface. For example:

# ifup eth0

• Set an apk repository and update the cache:

# setup-apkrepos
# apk update

• Install the following packages required to set up LVM and LUKS:

# apk add haveged lvm2 cryptsetup e2fsprogs syslinux

Optionally, you can install a different editor, such as nano, to edit files in later steps if you do not want to use VI.

• Optionally, start the haveged service for unpredictable random numbers used for encryption:

# rc-service haveged start

Creating the Partition Layout

Linux requires an unencrypted /boot/ partition to boot. You can assign the remaining space for the encrypted LVM physical volume (PV).

• Start the fdisk utility to set up partitions:

# fdisk /dev/vda

• Create the /boot/ partition:

• Enter n → p → 1 → 1 → 100m to create a new 100 MB primary partition.

• Set the /boot/ partition active:

• Enter a → 1.

• Create the LVM PV partition:

• Enter n → p → 2 to start creating the next partition. Press Enter to select the default start cylinder. Enter the size of partition. For example, 512m for 512 MB or 5g for 5 GB. Alternatively press Enter to set the maximum available size.

• Set the partition type for the LVM PV:

• Enter t → 2 → 8e

• To verify the settings, press p. The output shows, for example:

   Device Boot     Start       End     Blocks   Id System
/dev/vda1   *          1       100      50368+  83 Linux
/dev/vda2            101     10402    5192208   8e Linux LVM

• Press w to save the changes.

• Optionally, wipe the LVM PV partition with random values:

# haveged -n 0 | dd of=/dev/vda2

Depending on the size of the partition, this process can take several minutes to hours.

Encrypting the LVM Physical Volume Partition

• To encrypt the partition which will later contain the LVM PV:

# cryptsetup luksFormat /dev/vda2

Note: Alpine Linux uses the en-us keyboard mapping when prompting for the password to encrypt the partition at boot time. If you changed the keyboard map in the temporary environment, the password you enter during encrypting the partition in this step, may not match the password you will enter during the system boots.

If you prefer setting an individual hashing algorithm and hashing schema:

• To run a benchmark:

# cryptsetup benchmark

• To encrypt the partition using individual settings, enter, for example:

# cryptsetup -v -c serpent-xts-plain64 -s 512 --hash whirlpool --iter-time 5000 --use-random luksFormat /dev/vda2

Creating the Logical Volumes and File Systems

• Open the LUKS partition:

# cryptsetup open --type luks /dev/vda2 lvmcrypt

• Create the PV on /dev/vda:

# pvcreate /dev/mapper/lvmcrypt

• Create the vg0 LVM VG in the /dev/mapper/lvmcrypt PV:

# vgcreate vg0 /dev/mapper/lvmcrypt

• Create the LVs:

In the following you will create a LV for the root partition. However, you can use the same command with a different LV name to create further LVs for other mount points you want to create.

• To create a 2 GB LV named root in the vg0 VG:

# lvcreate -L 2G vg0 -n root

Create a 512 MB swap LV:

# lvcreate -L 512M vg0 -n swap

• The LVs created in the previous steps are automatically marked active. To verify, enter:

# lvscan

Format the root LV using the ext4 file system:

# mkfs.ext4 /dev/vg0/root

If you created further LVs in the previous step, create the file systems on them using the same command with the path to the LV.

• Format the swap LV:

# mkswap /dev/vg0/swap

• Format the /dev/vda1 device for the /boot/ partition using the ext4 file system:

# mkfs.ext4 /dev/vda1

Mounting the File Systems

Before you can install Alpine Linux, you must mount the partitions and LVs:

• Mount the root LV to the /mnt/ directory:

# mount /dev/vg0/root /mnt/

• Create /mnt/boot/ directory and mount the /dev/vda1 partition in this directory:

# mkdir -t ext4 /mnt/boot/
# mount -t ext4 /dev/vda1 /mnt/boot/

If you created further partitions or LVs, create the mount points within the /mnt/ directory and mount the devices.

Installing Alpine Linux

In this step you will install Alpine Linux in the /mnt/ directory, which contains the mounted file system structure:

• Install Alpine Linux:

# setup-disk -m sys /mnt/

The installer downloads the latest packages to install the base installation. Additionally, the installer automatically creates the entries for the mount points in the fstab file, which are currently mounted in the /mnt/ directory.

Note: The automatic writing of the master boot record (MBR) fails in this step. You will write the MBR later manually to the disk.

• To enable the operating system to decrypt the PV at boot time, create the /mnt/etc/crypttab file. Enter the following line into the file to decrypt the /dev/vda2 partition using the luks module and map it to the lvmcrypt name:

lvmcrypt    /dev/vda2    none    luks

• The swap LV is not automatically added to the fstab file. To add it manually, add the following line to the /mnt/etc/fstab file:

/dev/vg0/swap    swap    swap    defaults    0 0

• Edit the /mnt/etc/mkinitfs/mkinitfs.conf file and append the cryptsetup module to the features parameter:

features="ata base ide scsi usb virtio ext4 lvm cryptsetup"

• Rebuild the initial RAM disk:

# mkinitfs -c /mnt/etc/mkinitfs/mkinitfs.conf -b /mnt/ $(ls -1 /mnt/lib/modules/)

The command uses the settings from the mkinitfs.conf file set in the -c parameter to generate the RAM disk. The command is executed in the /mnt/ directory and the RAM disk is generated using the modules for the installed kernel. Without setting the kernel version using the $(ls -1 /mnt/lib/modules/) option, mkinitfs tries to generate the RAM disk using the kernel version installed in the temporary environment, which can differ from the latest one installed by the setup-disk utility.

• Edit the /mnt/etc/update-extlinux.conf file and append the following kernel options to the default_kernel_opts parameter:

default_kernel_opts="... cryptroot=/dev/vda2 cryptdm=lvmcrypt"

The cryptroot parameter sets the name of the device that contains the root file system. The cryptdm parameter sets the name of the mapping previously set in the crypttab file.

• Because the update-extlinux utility operators only on the /boot/ directory, temporarily change the root to the /mnt/ directory and update the boot loader configuration:

# chroot /mnt/
# update-extlinux
# exit

Ignore the errors the update-extlinux utility displays.

• Write the MBR to the /dev/vda device:

# dd bs=440 count=1 conv=notrunc if=/mnt/usr/share/syslinux/mbr.bin of=/dev/vda

Unmounting the Volumes and Partitions

• Umount /mnt/boot/ and /mnt/:

# umount /mnt/boot/
# umount /mnt/

Note: If you mounted further partitions or LVs below /mnt/, you must first unmount all of them before you can unmount /mnt/.

• Disable the swap partition:

# swapoff -a

• Deactivate the VG:

# vgchange -a n

• Close the lvmcrypt device:

# cryptsetup luksClose lvmcrypt

• Reboot the system:

# reboot

Troubleshooting

General Procedure

In case your system fails to boot, you can verify the settings and fix incorrect configurations:

• Prepare the temporary installation environment

• Activate the VGs:

# vgchange -a y

• Mount the file systems

• Verify that you run the steps described in the Installing Alpine Linux section correctly. Update the configuration if necessary.

• Unmount the volumes and partitions