lnorg/documentation
1
2
Fork 0
Code Issues 30 Pull requests Projects 6 Activity

docs:alpine-server-setup/installation.md: implement legacy, booster to mkinitfs and implement zlevis.

Browse source
This commit is contained in:
Luc Bijl 2024-12-24 13:14:52 +01:00
parent 35ee8a3320
commit b18efc9901
1 changed files with 34 additions and 51 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

85
docs/alpine-server-setup/installation.md
View file

@ -2,38 +2,36 @@
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. 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. First import and decrypt the system pool:
``` ```
# zpool import -N -R /mnt tank # zpool import -N -R /mnt tank
# zfs load-key -L file:///tmp/tank.key tank # zfs load-key -L file:///tmp/tank.key tank
``` ```
Mount the datasets in the system pool and decrypt the home dataset. Mount the datasets in the system pool and decrypt the home dataset:
``` ```
# zfs mount tank/root/alpine # mount tank/root/alpine /mnt -t zfs -o noatime
# zfs mount tank/home # zfs mount tank/home
# zfs mount tank/var # zfs mount tank/var
``` ```
Mount the ESP. Mount the ESP:
``` ```
# mkdir /mnt/esp # mkdir /mnt/esp
# mount /dev/md/esp /mnt/esp -t vfat # mount /dev/md/esp /mnt/esp -t vfat
``` ```
Then install Alpine Linux. Then install Alpine Linux:
``` ```
# export BOOTLOADER=none # export BOOTLOADER=none
# setup-disk -m sys /mnt # setup-disk -m sys /mnt
``` ```
> This will also add `grub` as bootloader which will be replaced but for now it will reside on the ESP. To have a functional chroot into the system, bind the system process directories:
To have a functional chroot into the system, bind the system process directories.
``` ```
# for dir in dev proc sys run; do # for dir in dev proc sys run; do
@ -67,7 +65,7 @@ clock_hctosys="NO"
clock_systohc="NO" clock_systohc="NO"
``` ```
Configure the ESP raid array to mount. Configure the ESP raid array to mount:
``` ```
# modprobe raid1 # modprobe raid1
@ -77,61 +75,50 @@ Configure the ESP raid array to mount.
# rc-update add mdadm-raid boot # rc-update add mdadm-raid boot
``` ```
Configure ZFS to mount. Configure ZFS to mount:
``` ```
rc-update add zfs-import sysinit rc-update add zfs-import sysinit
rc-update add zfs-mount 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: Edit `/etc/fstab` for correct mounts:
``` ```
/dev/md/esp /esp vfat defaults,nodev,nosuid,noexec 0 2 /dev/md/esp /esp vfat defaults,nodev,nosuid,noexec 0 2
tmpfs /tmp tmpfs rw,size=4G,nr_inodes=5k,nodev,nosuid,noexec,mode=1777 0 0 tmpfs /tmp tmpfs rw,nodev,nosuid,noexec,mode=1777 0 0
proc /proc proc nodev,nosuid,noexec,hidepid=2 0 0 proc /proc proc nodev,nosuid,noexec,hidepid=2 0 0
``` ```
By default, Alpine Linux uses `mkinitfs` to create an initial ram filesystem, although it is minimal that also means that it lacks some functionality which is needed for a proper setup. Because of this `mkinitfs` and `grub-efi `will be replaced with `booster` and `secureboot-hook`. Install the following packages to make `mkinitfs` compatible with secureboot and TPM decryption:
``` ```
# apk add booster secureboot-hook sbctl # apk add secureboot-hook sbctl tpm2-tools zlevis
# apk del mkinitfs grub-efi
``` ```
To configure booster edit `/etc/booster.yaml`: Configure `/etc/mkinitfs/mkinitfs.conf` to disable trigger and to add the `zlevis-hook`:
``` ```
enable_zfs: true features="... zlevis"
busybox: false disable_trigger="yes"
modules: vfat,nls_cp437,nls_iso8859_1
``` ```
The most important step is the creation of a UKI using `secureboot-hook` which also automatically signs them. First the hook itself will have to be tweaked to use `booster` instead of `mkinitfs`, edit `/etc/kernel-hooks.d/50-secureboot.hook` and change the line: 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:
``` ```
/sbin/mkinitfs -o "$tmpdir"/initramfs "$NEW_VERSION-$FLAVOR" cmdline="rw root=ZFS=tank/root/alpine rootflags=noatime quiet splash"
```
to: signing_cert="/var/lib/sbctl/keys/db/db.pem"
signing_key="/var/lib/sbctl/keys/db/db.key"
```
/usr/bin/booster build "$tmpdir"/initramfs --kernel-version "$NEW_VERSION-$FLAVOR"
```
and configure `/etc/kernel-hooks.d/secureboot.conf` for cmdline and secureboot.
```
cmdline="rw zfs=tank/root/alpine quiet splash"
signing_cert="/usr/share/secureboot/keys/db/db.pem"
signing_key="/usr/share/secureboot/keys/db/db.key"
output_dir="/esp/efi/linux" output_dir="/esp/efi/linux"
output_name="alpine-linux-{flavor}.efi" output_name="alpine-linux-{flavor}.efi"
``` ```
Use `sbctl` to create secureboot keys and sign them. Use `sbctl` to create secureboot keys and sign them:
``` ```
# sbctl create-keys # sbctl create-keys
@ -140,7 +127,7 @@ Use `sbctl` to create secureboot keys and sign them.
> Whilst enrolling the keys it might be necessary to add the `--microsoft` flag if you are unable to use custom 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. Set the cache-file of the ZFS pool:
``` ```
# zpool set cachefile=/etc/zfs/zpool.cache tank # zpool set cachefile=/etc/zfs/zpool.cache tank
@ -152,9 +139,15 @@ Now to see if everything went successfully, run:
# apk fix kernel-hooks # apk fix kernel-hooks
``` ```
Now to see if everything went successfully, run:
```
# apk fix kernel-hooks
```
and it should give no warnings if done properly. and it should give no warnings if done properly.
As discussed earlier `grub` will be replaced, install `gummiboot` as a bootloader. To install `gummiboot` as friendly bootloader:
``` ```
# apk add gummiboot # apk add gummiboot
@ -163,7 +156,7 @@ As discussed earlier `grub` will be replaced, install `gummiboot` as a bootloade
# cp /usr/lib/gummiboot/gummibootx64.efi /esp/efi/boot/bootx64.efi # cp /usr/lib/gummiboot/gummibootx64.efi /esp/efi/boot/bootx64.efi
``` ```
Sign the bootloader with `sbctl`. Sign the bootloader with `sbctl`:
``` ```
# sbctl sign -s /esp/efi/boot/bootx64.efi # sbctl sign -s /esp/efi/boot/bootx64.efi
@ -171,15 +164,7 @@ Sign the bootloader with `sbctl`.
> One may verify the signed files by running `sbctl verify`, in this case `ESP_PATH=/esp` should be defined to work properly. > One may verify the signed files by running `sbctl verify`, in this case `ESP_PATH=/esp` should be defined to work properly.
Remove some remnants of `grub`. `gummiboot` can be configured with the file `/esp/loader/loader.conf` with which the timeout and the default OS can be specified:
```
# rm -rf /boot/grub
# rm -rf /etc/default
# cd /boot && unlink boot && cd ..
```
`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 default alpine-linux-lts.efi
@ -187,8 +172,6 @@ timeout 2
editor no editor no
``` ```
> Here, there should be lines explaining the setup of automatic decryption with TPM using Clevis. Which is still in development...
Now exit the chroot and you should be able to reboot into a working Alpine system. Now exit the chroot and you should be able to reboot into a working Alpine system.
``` ```