documentation/docs/alpine-server-setup/installation.md

Installation

To install the Alpine Linux distribution on the system, the datasets of the system pool and the EFI partitions have to be mounted to the main system.

First import and decrypt the system pool:

# zpool import -N -R /mnt rpool
# zfs load-key -L file:///tmp/rpool.key rpool

Mount the datasets in the system pool and decrypt the home dataset:

# mount rpool/root/alpine /mnt -t zfs -o noatime
# zfs mount rpool/home
# zfs mount rpool/var

Mount the ESP:

# mkdir /mnt/esp
# mount /dev/md/esp /mnt/esp -t vfat

Then install Alpine Linux:

# export BOOTLOADER=none
# setup-disk -m sys /mnt

To have a functional chroot into the system, bind the system process directories:

# for dir in dev proc sys run; do
> mount --rbind --make-rslave /$dir /mnt/$dir
> done
# chroot /mnt

The other setup scripts can be used to configure key aspects of the system. Besides that a few necessary services have to be activated.

# setup-hostname <hostname>
# setup-keymap us us-euro
# setup-timezone -i <area>/<subarea>
# setup-ntp openntpd
# setup-sshd -c dropbear
# rc-update add acpid default
# rc-update add seedrng boot
# rm -rf /var/tmp
# ln -s /tmp /var/tmp
# passwd root

The root password does not really matter because it is going to be locked after a user has been created.

Set the hwclock to use UTC in /etc/conf.d/hwclock and disable writing the time to hardware. Running a NTP negates its usability.

clock="UTC"
clock_hctosys="NO"
clock_systohc="NO"

Configure the ESP raid array to mount:

# modprobe raid1
# echo raid1 >> /etc/modules-load.d/raid1.conf
# mdadm --detail --scan >> /etc/mdadm.conf
# rc-update add mdadm boot
# rc-update add mdadm-raid boot

Configure ZFS to mount:

rc-update add zfs-import sysinit
rc-update add zfs-mount sysinit
rc-update add zfs-load-key sysinit

If a faster boot time is preferred, zfs-import and zfs-load-key can be omitted in certain cases.

Edit /etc/fstab for correct mounts:

/dev/md/esp    /esp        vfat    defaults,nodev,nosuid,noexec         0 2
tmpfs          /tmp        tmpfs   rw,nodev,nosuid,noexec,mode=1777     0 0
proc           /proc       proc    nodev,nosuid,noexec,hidepid=2        0 0

Install the following packages to make mkinitfs compatible with secureboot and TPM decryption:

# apk add secureboot-hook sbctl tpm2-tools zlevis 

Configure /etc/mkinitfs/mkinitfs.conf to disable trigger and to add the zlevis-hook:

features="... zlevis"
disable_trigger="yes"

The mkinitfs package that supports zlevis is as of this moment not yet in the alpine package repository, for the relevant steps see the zlevis mkinitfs-implementation wiki.

The most important step is the creation of a UKI using secureboot-hook which also automatically signs them. Configure /etc/kernel-hooks.d/secureboot.conf to set kernel cmdline options and secureboot:

cmdline="rw root=ZFS=rpool/root/alpine rootflags=noatime quiet splash"

signing_cert="/var/lib/sbctl/keys/db/db.pem"
signing_key="/var/lib/sbctl/keys/db/db.key"

output_dir="/esp/efi/linux"
output_name="alpine-linux-{flavor}.efi"

Use sbctl to create secureboot keys and sign them:

# sbctl create-keys
# sbctl enroll-keys

Whilst enrolling the keys it might be necessary to add the --microsoft flag if you are unable to use custom keys.

Set the cache-file of the ZFS pool:

# zpool set cachefile=/etc/zfs/zpool.cache rpool

Now to see if everything went successfully, run:

# apk fix kernel-hooks

and it should give no warnings if done properly.

To install gummiboot as friendly bootloader:

# apk add gummiboot
# mkdir /esp/loader
# mkdir /esp/efi/boot
# cp /usr/lib/gummiboot/gummibootx64.efi /esp/efi/boot/bootx64.efi

Sign the bootloader with sbctl:

# sbctl sign -s /esp/efi/boot/bootx64.efi

One may verify the signed files by running sbctl verify, in this case ESP_PATH=/esp should be defined to work properly.

gummiboot can be configured with the file /esp/loader/loader.conf with which the timeout and the default OS can be specified:

default alpine-linux-lts.efi
timeout 2
editor no

Now exit the chroot and you should be able to reboot into a working Alpine system.

# exit
# umount -lf /mnt
# zpool export rpool
# reboot