Alpine Linux - User contributions [en]

Immutable root with atomic upgrades

2023-11-30T09:32:59Z

Mvsn: Improved sysmut script

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using a modern bootloader and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with the ability to easily rollback or boot previous configurations is a concept that has been gaining popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has its killer features, it lacks the ones mentioned above on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it is described on the [[Installation|installation page.]]

= Partitioning disks =
In this guide, it's assumed that you have a fresh UEFI system without an OS and have just booted into a live Alpine system using a USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create the file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var
# btrfs subvolume create /mnt/commons/@home</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the [[BTRFS|btrfs]] root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var btrfs subvol=/commons/@var,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root [[BTRFS|btrfs]] volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory structure prepared, we can begin installing a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you're in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
This example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for the firmware, kernel, and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for your system, for example, <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for a typical AMD laptop. 
It's also important to add the <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare the kernel and generate the <code>initramfs</code>, which will be used later to boot from our first snapshot. 
After that, you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install the <code>openresolv</code> package to support changing the network connection. In this case, <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code>, and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

Don't forget to add essential services to their respective runlevels:
<pre>rc-update add devfs sysinit
rc-update add dmesg sysinit
rc-update add mdev sysinit
rc-update add hwdrivers sysinit

rc-update add hwclock boot
rc-update add modules boot
rc-update add sysctl boot
rc-update add hostname boot
rc-update add bootmisc boot
rc-update add syslog boot

rc-update add mount-ro shutdown
rc-update add killprocs shutdown
rc-update add savecache shutdown</pre>

With the snapshot prepared and configured, we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing the snapshot by setting the <code>ro</code> flag and unmounting the root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
== Bootloader configuration ==
There are 2 options as examples of the bootloader installation: <code>rEFInd</code> and <code>GRUB</code>.
Sometimes one of them will refuse to work on a system for no particular reason, in this case try the other one.
=== rEFInd ===
Check the latest version number of the <code>refind</code> package:
<pre># apk info -X https://dl-cdn.alpinelinux.org/alpine/edge/testing -U refind</pre>
Download the latest version (replace 0.13.2-r3 in the example below) of the <code>refind</code> package:
<pre># wget https://dl-cdn.alpinelinux.org/alpine/edge/testing/x86_64/refind-0.13.2-r3.apk</pre>
Unpack the prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># tar -xzf refind-0.13.2-r3.apk
# cp -r usr/share/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> ([[BTRFS|btrfs]] partition) and <code>resume</code> (swap partition). Keep in mind that if you named the btrfs volume other than <code>ROOT</code> during "Partitioning disks" stage, you have to change the <code>volume</code> field below accordingly.
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the [[BTRFS|btrfs]] partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
=== GRUB ===
<pre># apk add grub-efi</pre>
GRUB requires two configuration files this time as we will use <code>grub-mkstandalone</code>.
The first configuration file is internal and should only point to the second file, where we store the menu:
<pre># cd /tmp
# vi grub_internal.cfg</pre>
Set the contents to the following, but make sure to replace <code>2FE6-837A</code> with your own EFI partition UUID:
<pre>insmod part_gpt
insmod fat
search --set efi --fs-uuid 2FE6-837A
configfile (${efi})/EFI/grub/grub.cfg</pre>
The second config file is the main config where we describe the entire boot menu.
<pre># vi grub.cfg</pre>
Set to contain, but replace UUIDs:
<pre>set timeout=3
menuentry "Alpine Linux Current" {
search --set root --fs-uuid b9ff5e7b-e128-4e64-861a-2fdd794a9828
linux /current/0/@/boot/vmlinuz-edge root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash
initrd /current/0/@/boot/initramfs-edge
}
menuentry "Alpine Linux Snapshot 1" {
search --set root --fs-uuid b9ff5e7b-e128-4e64-861a-2fdd794a9828
linux /current/1/@/boot/vmlinuz-edge root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash
initrd /current/1/@/boot/initramfs-edge
}
menuentry "Alpine Linux Snapshot 2" {
search --set root --fs-uuid b9ff5e7b-e128-4e64-861a-2fdd794a9828
linux /current/2/@/boot/vmlinuz-edge root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash
initrd /current/2/@/boot/initramfs-edge
}
menuentry "Alpine Linux Snapshot 3" {
search --set root --fs-uuid b9ff5e7b-e128-4e64-861a-2fdd794a9828
linux /current/3/@/boot/vmlinuz-edge root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash
initrd /current/3/@/boot/initramfs-edge
}</pre>
Generate the <code>grubx64.efi</code> binary:
<pre># grub-mkstandalone -O x86_64-efi -o grubx64.efi "boot/grub/grub.cfg=/tmp/grub_internal.cfg"
# mkdir /mnt/EFI/grub
# mv grubx64.efi /mnt/EFI/grub/
# mv grub.cfg /mnt/EFI/grub/</pre>

== Adding EFI boot entry ==
To add the chosen bootloader to UEFI, <code>efibootmgr</code> is a suitable tool. The following example is for rEFInd, but could be easily adjusted for GRUB:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of the FAT32 partition containing the bootloader data.

= Updating or altering the system =
{{Warning|Without the following step or an alternative you will have no easy way to mutate the installed system.}}
{{Warning|These examples are implemented using <code>execline</code> and require the <code>execline</code> package in the system.}}
{{Note|These could surely be implemented in POSIX shell, however, <code>execline</code> provides a number of runtime advantages and the resulting script is much more readable.}}
<pre># touch /usr/sbin/sysmut
# chmod +x /usr/sbin/sysmut
# vi /usr/sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/execlineb -W
unshare --mount
importas -D 0 source 1
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
backtick -E dt {
date -u +%Y%m%d%H%M%S
}
backtick -E rnd {
pipeline { cat /dev/urandom }
pipeline { tr -dc a-zA-Z }
pipeline { fold -w 8 }
head -n 1
}
define newsnap ${dt}${rnd}
if { mkdir -p ${mnt}/snapshots/${newsnap} }
if { btrfs subvolume snapshot ${mnt}/current/${source}/@ ${mnt}/snapshots/${newsnap}/@ }
if {
redirfd -w 1 ${mnt}/snapshots/${newsnap}/@/etc/fstab
sed s#CURRENT_SNAPSHOTS_PATH#/snapshots/${newsnap}#g ${mnt}/fstab
}
if { mount -t proc none ${mnt}/snapshots/${newsnap}/@/proc }
if { mount -t sysfs sys ${mnt}/snapshots/${newsnap}/@/sys }
if { mount -o bind,ro /dev ${mnt}/snapshots/${newsnap}/@/dev }
foreground {
foreground { mount -o bind,ro /etc/resolv.conf ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
foreground {
chroot ${mnt}/snapshots/${newsnap}/@
foreground { mount -a }
foreground { sh }
importas apply ?
foreground { umount -a }
exit ${apply}
}
importas apply ?
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
ifelse { exit ${apply} } {
if { btrfs property set -ts ${mnt}/snapshots/${newsnap}/@ ro true }
define newlink ${dt}${rnd}
if { mkdir -p ${mnt}/links/${newlink} }
if { ln -s ../../snapshots/${newsnap} ${mnt}/links/${newlink}/0 }
if { cp -P ${mnt}/current/0 ${mnt}/links/${newlink}/1 }
if { cp -P ${mnt}/current/1 ${mnt}/links/${newlink}/2 }
if { cp -P ${mnt}/current/2 ${mnt}/links/${newlink}/3 }
if { mkdir -p ${mnt}/next }
if { ln -sfn ./links/${newlink} ${mnt}/next/current }
if { mv ${mnt}/next/current ${mnt}/ }
echo "Changes applied"
}
echo "Changes discarded"
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/proc }
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/sys }
redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/dev
}
umount ${mnt}
</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. The origin of the new snapshot is defined by the first and only argument, in form of number. If no argument provided the <code>0</code> (current latest) is taken as origin. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /usr/sbin/syscln
# chmod +x /usr/sbin/syscln
# vi /usr/sbin/syscln</pre>

<pre>#!/bin/execlineb -W
unshare --mount
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime,compress=zstd:3 UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline {
find -H ${mnt}/current/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r btrfs subvolume delete
}
foreground { find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -empty -type d -delete }
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
realpath ${mnt}/current
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r -n 1 unlink
}
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -empty -type d -delete
}
umount ${mnt}
</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use of this, add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

[[Category:Installation]][[Category:File systems]]

Immutable root with atomic upgrades

2023-11-21T17:13:54Z

Mvsn: Add GRUB as an alternative bootloader

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using a modern bootloader and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var
# btrfs subvolume create /mnt/commons/@home</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the [[BTRFS|btrfs]] root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var btrfs subvol=/commons/@var,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root [[BTRFS|btrfs]] volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

Don't forget to add essential services to their respective runlevels:
<pre>rc-update add devfs sysinit
rc-update add dmesg sysinit
rc-update add mdev sysinit
rc-update add hwdrivers sysinit

rc-update add hwclock boot
rc-update add modules boot
rc-update add sysctl boot
rc-update add hostname boot
rc-update add bootmisc boot
rc-update add syslog boot

rc-update add mount-ro shutdown
rc-update add killprocs shutdown
rc-update add savecache shutdown</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
== Bootloader configuration ==
There are 2 options as examples of the bootloader installation: <code>rEFInd</code> and <code>GRUB</code>.
Sometimes one of them will refuse to work on a system for no paticular reason, in this case try the other one.
=== rEFInd ===
Check the latest version number of the <code>refind</code> package:
<pre># apk info -X https://dl-cdn.alpinelinux.org/alpine/edge/testing -U refind</pre>
Download the latest version (replace 0.13.2-r3 in the example below) of the <code>refind</code> package:
<pre># wget https://dl-cdn.alpinelinux.org/alpine/edge/testing/x86_64/refind-0.13.2-r3.apk</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># tar -xzf refind-0.13.2-r3.apk
# cp -r usr/share/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> ([[BTRFS|btrfs]] partition) and <code>resume</code> (swap partition). Keep in mind that if you named the btrfs volume other than <code>ROOT</code> during "Partitioning disks" stage, you have to change the <code>volume</code> field below accordingly.
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the [[BTRFS|btrfs]] partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
=== GRUB ===
<pre># apk add grub-efi</pre>
GRUB requires two configuration files this time as we will use <code>grub-mkstandalone</code>.
The first configuration file is internal and should only point to the second file, where we store the menu:
<pre># cd /tmp
# vi grub_internal.cfg</pre>
Set the contents to the following, but make sure to replace <code>2FE6-837A</code> with your own EFI partition UUID:
<pre>insmod part_gpt
insmod fat
search --set efi --fs-uuid 2FE6-837A
configfile (${efi})/EFI/grub/grub.cfg</pre>
Second config file is the main config where we decribe the whole boot menu.
<pre># vi grub.cfg</pre>
Set to contain, but replace UUIDs:
<pre>set timeout=3
menuentry "Alpine Linux Current" {
search --set root --fs-uuid b9ff5e7b-e128-4e64-861a-2fdd794a9828
linux /current/0/@/boot/vmlinuz-edge root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash
initrd /current/0/@/boot/initramfs-edge
}
menuentry "Alpine Linux Snapshot 1" {
search --set root --fs-uuid b9ff5e7b-e128-4e64-861a-2fdd794a9828
linux /current/1/@/boot/vmlinuz-edge root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash
initrd /current/1/@/boot/initramfs-edge
}
menuentry "Alpine Linux Snapshot 2" {
search --set root --fs-uuid b9ff5e7b-e128-4e64-861a-2fdd794a9828
linux /current/2/@/boot/vmlinuz-edge root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash
initrd /current/2/@/boot/initramfs-edge
}
menuentry "Alpine Linux Snapshot 3" {
search --set root --fs-uuid b9ff5e7b-e128-4e64-861a-2fdd794a9828
linux /current/3/@/boot/vmlinuz-edge root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash
initrd /current/3/@/boot/initramfs-edge
}</pre>
Generate the <code>grubx64.efi</code> binary:
<pre># grub-mkstandalone -O x86_64-efi -o grubx64.efi "boot/grub/grub.cfg=/tmp/grub_internal.cfg"
# mkdir /mnt/EFI/grub
# mv grubx64.efi /mnt/EFI/grub/
# mv grub.cfg /mnt/EFI/grub/</pre>

== Adding EFI boot entry ==
To add the chosen bootloader to UEFI, <code>efibootmgr</code> is a suitable tool. The following example is for rEFInd, but could be easily adjusted for GRUB:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of the FAT32 partition containing the bootloader data.

= Updating or altering the system =
{{Warning|Without the following step or an alternative you will have no easy way to mutate the installed system.}}
{{Warning|These examples are implemented using <code>execline</code> and require the <code>execline</code> package in the system.}}
{{Note|These could surely be implemented in POSIX shell, however <code>execline</code> provides number of runtime advantages and the script in it is much more readable.}}
<pre># touch /usr/sbin/sysmut
# chmod +x /usr/sbin/sysmut
# vi /usr/sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/execlineb -W
unshare --mount
importas -D 0 source 1
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
backtick -E dt {
date -u +%Y%m%d%H%M%S
}
backtick -E rnd {
pipeline { cat /dev/urandom }
pipeline { tr -dc a-zA-Z }
pipeline { fold -w 8 }
head -n 1
}
define newsnap ${dt}${rnd}
if { mkdir -p ${mnt}/snapshots/${newsnap} }
if { btrfs subvolume snapshot ${mnt}/current/${source}/@ ${mnt}/snapshots/${newsnap}/@ }
if {
redirfd -w 1 ${mnt}/snapshots/${newsnap}/@/etc/fstab
sed s#CURRENT_SNAPSHOTS_PATH#/snapshots/${newsnap}#g ${mnt}/fstab
}
if { mount -t proc none ${mnt}/snapshots/${newsnap}/@/proc }
if { mount -t sysfs sys ${mnt}/snapshots/${newsnap}/@/sys }
if { mount -o bind,ro /dev ${mnt}/snapshots/${newsnap}/@/dev }
foreground {
foreground { mount -o bind,ro /etc/resolv.conf ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if {
chroot ${mnt}/snapshots/${newsnap}/@
foreground { mount -a }
foreground { sh }
importas apply ?
foreground { umount -a }
exit ${apply}
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if { btrfs property set -ts ${mnt}/snapshots/${newsnap}/@ ro true }
define newlink ${dt}${rnd}
if { mkdir -p ${mnt}/links/${newlink} }
if { ln -s ../../snapshots/${newsnap} ${mnt}/links/${newlink}/0 }
if { cp -P ${mnt}/current/0 ${mnt}/links/${newlink}/1 }
if { cp -P ${mnt}/current/1 ${mnt}/links/${newlink}/2 }
if { cp -P ${mnt}/current/2 ${mnt}/links/${newlink}/3 }
if { mkdir -p ${mnt}/next }
if { ln -sfn ./links/${newlink} ${mnt}/next/current }
if { mv ${mnt}/next/current ${mnt}/ }
echo "Switched to the new snapshot"
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/proc }
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/sys }
redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/dev
}
umount ${mnt}
</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /usr/sbin/syscln
# chmod +x /usr/sbin/syscln
# vi /usr/sbin/syscln</pre>

<pre>#!/bin/execlineb -W
unshare --mount
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime,compress=zstd:3 UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline {
find -H ${mnt}/current/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r btrfs subvolume delete
}
foreground { find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -empty -type d -delete }
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
realpath ${mnt}/current
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r -n 1 unlink
}
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -empty -type d -delete
}
umount ${mnt}
</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

[[Category:Installation]][[Category:File systems]]

Talk:Immutable root with atomic upgrades

2023-11-04T18:46:28Z

Mvsn:

[[User:Sb1]], regarding diskless mode note: thanks for reminding about it, but it's a different setup with its own features, so I reduced the note, but left the links. Similar guide to diskless chroot setup would be really appreciated btw. [[User:Mvsn|Mvsn]] ([[User talk:Mvsn|talk]]) 23:04, 31 May 2021 (UTC)

== rEFInd ==

The rEFInd configuration provided in this does not appear to work universally, as rEFInd assumes that the <code>loader</code> and <code>initrd</code> parameters in the MenuEntry are located within the ESP partition. To produce a bootable version of this setup, I had to move my kernel and my initramfs to the ESP partition.— Preceding unsigned comments added by [[User:Machinestops|Machinestops ]] ([[User talk:Machinestops #top|talk]] • [[Special:Contributions/Machinestops |contribs]]) 12:01, 31 May 2023‎

[[User:Machinestops|Machinestops]], not sure I follow. The config field <code>volume</code> defines which partition contains the path defined in the fields <code>loader</code> and <code>initrd</code>. If you have btrfs volume with the label other than <code>ROOT</code>, you have to also change <code>volume</code> field in the config. Kernel and initramfs should reside in the btrfs volume, they are the part of the snapshot. [[User:Mvsn|Mvsn]] ([[User talk:Mvsn|talk]])

== System mutation scripts ==

It might be helpful to note that <code>execline</code> should be included in the list of packages installed while setting up the initial root snapshot, and also that the scripts provided should be downloaded (perhaps provide them as raw files somehow?). Without them, there is no way to modify the system other than manually mounting, creating an RW snapshot, and performing the link migration manually, which might prove bothersome for some (or unclear).

Documenting the functionality of the scripts with comments might also be useful. The level of piping and nesting in these scripts makes it difficult to follow along for anyone unfamiliar with <code>execline</code>.— Preceding unsigned comments added by [[User:Machinestops|Machinestops ]] ([[User talk:Machinestops #top|talk]] • [[Special:Contributions/Machinestops |contribs]]) 12:10, 31 May 2023‎

Immutable root with atomic upgrades

2023-11-04T18:41:59Z

Mvsn: simplify setup by using common non-snapshotted /var

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var
# btrfs subvolume create /mnt/commons/@home</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the [[BTRFS|btrfs]] root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var btrfs subvol=/commons/@var,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root [[BTRFS|btrfs]] volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

Don't forget to add essential services to their respective runlevels:
<pre>rc-update add devfs sysinit
rc-update add dmesg sysinit
rc-update add mdev sysinit
rc-update add hwdrivers sysinit

rc-update add hwclock boot
rc-update add modules boot
rc-update add sysctl boot
rc-update add hostname boot
rc-update add bootmisc boot
rc-update add syslog boot

rc-update add mount-ro shutdown
rc-update add killprocs shutdown
rc-update add savecache shutdown</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports [[BTRFS|btrfs]] and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Check the latest version number of the <code>refind</code> package:
<pre># apk info -X https://dl-cdn.alpinelinux.org/alpine/edge/testing -U refind</pre>
Download the latest version (replace 0.13.2-r3 in the example below) of the <code>refind</code> package:
<pre># wget https://dl-cdn.alpinelinux.org/alpine/edge/testing/x86_64/refind-0.13.2-r3.apk</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># tar -xzf refind-0.13.2-r3.apk
# cp -r usr/share/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> ([[BTRFS|btrfs]] partition) and <code>resume</code> (swap partition). Keep in mind that if you named the btrfs volume other than <code>ROOT</code> during "Partitioning disks" stage, you have to change the <code>volume</code> field below accordingly.
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the [[BTRFS|btrfs]] partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
{{Warning|Without the following step or an alternative you will have no easy way to mutate the installed system.}}
{{Warning|These examples are implemented using <code>execline</code> and require the <code>execline</code> package in the system.}}
{{Note|These could surely be implemented in POSIX shell, however <code>execline</code> provides number of runtime advantages and the script in it is much more readable.}}
<pre># touch /usr/sbin/sysmut
# chmod +x /usr/sbin/sysmut
# vi /usr/sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/execlineb -W
unshare --mount
importas -D 0 source 1
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
backtick -E dt {
date -u +%Y%m%d%H%M%S
}
backtick -E rnd {
pipeline { cat /dev/urandom }
pipeline { tr -dc a-zA-Z }
pipeline { fold -w 8 }
head -n 1
}
define newsnap ${dt}${rnd}
if { mkdir -p ${mnt}/snapshots/${newsnap} }
if { btrfs subvolume snapshot ${mnt}/current/${source}/@ ${mnt}/snapshots/${newsnap}/@ }
if {
redirfd -w 1 ${mnt}/snapshots/${newsnap}/@/etc/fstab
sed s#CURRENT_SNAPSHOTS_PATH#/snapshots/${newsnap}#g ${mnt}/fstab
}
if { mount -t proc none ${mnt}/snapshots/${newsnap}/@/proc }
if { mount -t sysfs sys ${mnt}/snapshots/${newsnap}/@/sys }
if { mount -o bind,ro /dev ${mnt}/snapshots/${newsnap}/@/dev }
foreground {
foreground { mount -o bind,ro /etc/resolv.conf ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if {
chroot ${mnt}/snapshots/${newsnap}/@
foreground { mount -a }
foreground { sh }
importas apply ?
foreground { umount -a }
exit ${apply}
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if { btrfs property set -ts ${mnt}/snapshots/${newsnap}/@ ro true }
define newlink ${dt}${rnd}
if { mkdir -p ${mnt}/links/${newlink} }
if { ln -s ../../snapshots/${newsnap} ${mnt}/links/${newlink}/0 }
if { cp -P ${mnt}/current/0 ${mnt}/links/${newlink}/1 }
if { cp -P ${mnt}/current/1 ${mnt}/links/${newlink}/2 }
if { cp -P ${mnt}/current/2 ${mnt}/links/${newlink}/3 }
if { mkdir -p ${mnt}/next }
if { ln -sfn ./links/${newlink} ${mnt}/next/current }
if { mv ${mnt}/next/current ${mnt}/ }
echo "Switched to the new snapshot"
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/proc }
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/sys }
redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/dev
}
umount ${mnt}
</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /usr/sbin/syscln
# chmod +x /usr/sbin/syscln
# vi /usr/sbin/syscln</pre>

<pre>#!/bin/execlineb -W
unshare --mount
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime,compress=zstd:3 UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline {
find -H ${mnt}/current/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r btrfs subvolume delete
}
foreground { find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -empty -type d -delete }
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
realpath ${mnt}/current
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r -n 1 unlink
}
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -empty -type d -delete
}
umount ${mnt}
</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

[[Category:Installation]][[Category:File systems]]

Immutable root with atomic upgrades

2023-11-04T18:22:54Z

Mvsn: add notes and warnings for some steps

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example iwd and bluetooth:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd
# btrfs subvolume create /mnt/commons/@var@lib@bluetooth</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the [[BTRFS|btrfs]] root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/bluetooth btrfs subvol=/commons/@var@lib@bluetooth,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root [[BTRFS|btrfs]] volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

Don't forget to add essential services to their respective runlevels:
<pre>rc-update add devfs sysinit
rc-update add dmesg sysinit
rc-update add mdev sysinit
rc-update add hwdrivers sysinit

rc-update add hwclock boot
rc-update add modules boot
rc-update add sysctl boot
rc-update add hostname boot
rc-update add bootmisc boot
rc-update add syslog boot

rc-update add mount-ro shutdown
rc-update add killprocs shutdown
rc-update add savecache shutdown</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports [[BTRFS|btrfs]] and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Check the latest version number of the <code>refind</code> package:
<pre># apk info -X https://dl-cdn.alpinelinux.org/alpine/edge/testing -U refind</pre>
Download the latest version (replace 0.13.2-r3 in the example below) of the <code>refind</code> package:
<pre># wget https://dl-cdn.alpinelinux.org/alpine/edge/testing/x86_64/refind-0.13.2-r3.apk</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># tar -xzf refind-0.13.2-r3.apk
# cp -r usr/share/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> ([[BTRFS|btrfs]] partition) and <code>resume</code> (swap partition). Keep in mind that if you named the btrfs volume other than <code>ROOT</code> during "Partitioning disks" stage, you have to change the <code>volume</code> field below accordingly.
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the [[BTRFS|btrfs]] partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
{{Warning|Without the following step or an alternative you will have no easy way to mutate the installed system.}}
{{Warning|These examples are implemented using <code>execline</code> and require the <code>execline</code> package in the system.}}
{{Note|These could surely be implemented in POSIX shell, however <code>execline</code> provides number of runtime advantages and the script in it is much more readable.}}
<pre># touch /usr/sbin/sysmut
# chmod +x /usr/sbin/sysmut
# vi /usr/sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/execlineb -W
unshare --mount
importas -D 0 source 1
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
backtick -E dt {
date -u +%Y%m%d%H%M%S
}
backtick -E rnd {
pipeline { cat /dev/urandom }
pipeline { tr -dc a-zA-Z }
pipeline { fold -w 8 }
head -n 1
}
define newsnap ${dt}${rnd}
if { mkdir -p ${mnt}/snapshots/${newsnap} }
if { btrfs subvolume snapshot ${mnt}/current/${source}/@ ${mnt}/snapshots/${newsnap}/@ }
if {
redirfd -w 1 ${mnt}/snapshots/${newsnap}/@/etc/fstab
sed s#CURRENT_SNAPSHOTS_PATH#/snapshots/${newsnap}#g ${mnt}/fstab
}
if { mount -t proc none ${mnt}/snapshots/${newsnap}/@/proc }
if { mount -t sysfs sys ${mnt}/snapshots/${newsnap}/@/sys }
if { mount -o bind,ro /dev ${mnt}/snapshots/${newsnap}/@/dev }
foreground {
foreground { mount -o bind,ro /etc/resolv.conf ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if {
chroot ${mnt}/snapshots/${newsnap}/@
foreground { mount -a }
foreground { sh }
importas apply ?
foreground { umount -a }
exit ${apply}
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if { btrfs property set -ts ${mnt}/snapshots/${newsnap}/@ ro true }
define newlink ${dt}${rnd}
if { mkdir -p ${mnt}/links/${newlink} }
if { ln -s ../../snapshots/${newsnap} ${mnt}/links/${newlink}/0 }
if { cp -P ${mnt}/current/0 ${mnt}/links/${newlink}/1 }
if { cp -P ${mnt}/current/1 ${mnt}/links/${newlink}/2 }
if { cp -P ${mnt}/current/2 ${mnt}/links/${newlink}/3 }
if { mkdir -p ${mnt}/next }
if { ln -sfn ./links/${newlink} ${mnt}/next/current }
if { mv ${mnt}/next/current ${mnt}/ }
echo "Switched to the new snapshot"
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/proc }
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/sys }
redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/dev
}
umount ${mnt}
</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /usr/sbin/syscln
# chmod +x /usr/sbin/syscln
# vi /usr/sbin/syscln</pre>

<pre>#!/bin/execlineb -W
unshare --mount
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime,compress=zstd:3 UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline {
find -H ${mnt}/current/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r btrfs subvolume delete
}
foreground { find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -empty -type d -delete }
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
realpath ${mnt}/current
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r -n 1 unlink
}
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -empty -type d -delete
}
umount ${mnt}
</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

[[Category:Installation]][[Category:File systems]]

Talk:Immutable root with atomic upgrades

2023-11-04T18:09:49Z

Mvsn:

[[User:Sb1]], regarding diskless mode note: thanks for reminding about it, but it's a different setup with its own features, so I reduced the note, but left the links. Similar guide to diskless chroot setup would be really appreciated btw. [[User:Mvsn|Mvsn]] ([[User talk:Mvsn|talk]]) 23:04, 31 May 2021 (UTC)

== rEFInd ==

The rEFInd configuration provided in this does not appear to work universally, as rEFInd assumes that the <code>loader</code> and <code>initrd</code> parameters in the MenuEntry are located within the ESP partition. To produce a bootable version of this setup, I had to move my kernel and my initramfs to the ESP partition.— Preceding unsigned comments added by [[User:Machinestops|Machinestops ]] ([[User talk:Machinestops #top|talk]] • [[Special:Contributions/Machinestops |contribs]]) 12:01, 31 May 2023‎

[[User:Machinestops|Machinestops]], not sure I follow. The config field <code>volume</code> defines which partition contains the path defined in the fields <code>loader</code> and <code>initrd</code>. If you have btrfs volume with the label other than <code>ROOT</code>, you have to also change <code>volume</code> field in the config. Kernel and initramfs should reside in the btrfs volume, they are the part of the snapshot. [[User:Mvsn|Mvsn]] ([[User talk:Mvsn|talk]]) 23:04, 31 May 2021 (UTC)

== System mutation scripts ==

It might be helpful to note that <code>execline</code> should be included in the list of packages installed while setting up the initial root snapshot, and also that the scripts provided should be downloaded (perhaps provide them as raw files somehow?). Without them, there is no way to modify the system other than manually mounting, creating an RW snapshot, and performing the link migration manually, which might prove bothersome for some (or unclear).

Documenting the functionality of the scripts with comments might also be useful. The level of piping and nesting in these scripts makes it difficult to follow along for anyone unfamiliar with <code>execline</code>.— Preceding unsigned comments added by [[User:Machinestops|Machinestops ]] ([[User talk:Machinestops #top|talk]] • [[Special:Contributions/Machinestops |contribs]]) 12:10, 31 May 2023‎

Immutable root with atomic upgrades

2022-02-06T08:39:01Z

Mvsn:

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the [[BTRFS|btrfs]] root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root [[BTRFS|btrfs]] volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

Don't forget to add essential services to their respective runlevels:
<pre>rc-update add devfs sysinit
rc-update add dmesg sysinit
rc-update add mdev sysinit
rc-update add hwdrivers sysinit

rc-update add hwclock boot
rc-update add modules boot
rc-update add sysctl boot
rc-update add hostname boot
rc-update add bootmisc boot
rc-update add syslog boot

rc-update add mount-ro shutdown
rc-update add killprocs shutdown
rc-update add savecache shutdown</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports [[BTRFS|btrfs]] and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Check the latest version number of the <code>refind</code> package:
<pre># apk info -X https://dl-cdn.alpinelinux.org/alpine/edge/testing -U refind</pre>
Download the latest version (replace 0.13.2-r3 in the example below) of the <code>refind</code> package:
<pre># wget https://dl-cdn.alpinelinux.org/alpine/edge/testing/x86_64/refind-0.13.2-r3.apk</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># tar -xzf refind-0.13.2-r3.apk
# cp -r usr/share/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> ([[BTRFS|btrfs]] partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the [[BTRFS|btrfs]] partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
{{Note|These examples are implemented using execline and require <code>execline</code> package in the system. These could surely be implemented in POSIX shell, however execline provides number of runtime advantages and is much more readable.}}
<pre># touch /usr/sbin/sysmut
# chmod +x /usr/sbin/sysmut
# vi /usr/sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/execlineb -W
unshare --mount
importas -D 0 source 1
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
backtick -E dt {
date -u +%Y%m%d%H%M%S
}
backtick -E rnd {
pipeline { cat /dev/urandom }
pipeline { tr -dc a-zA-Z }
pipeline { fold -w 8 }
head -n 1
}
define newsnap ${dt}${rnd}
if { mkdir -p ${mnt}/snapshots/${newsnap} }
if { btrfs subvolume snapshot ${mnt}/current/${source}/@ ${mnt}/snapshots/${newsnap}/@ }
if {
redirfd -w 1 ${mnt}/snapshots/${newsnap}/@/etc/fstab
sed s#CURRENT_SNAPSHOTS_PATH#/snapshots/${newsnap}#g ${mnt}/fstab
}
if { mount -t proc none ${mnt}/snapshots/${newsnap}/@/proc }
if { mount -t sysfs sys ${mnt}/snapshots/${newsnap}/@/sys }
if { mount -o bind,ro /dev ${mnt}/snapshots/${newsnap}/@/dev }
foreground {
foreground { mount -o bind,ro /etc/resolv.conf ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if {
chroot ${mnt}/snapshots/${newsnap}/@
foreground { mount -a }
foreground { sh }
importas apply ?
foreground { umount -a }
exit ${apply}
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if { btrfs property set -ts ${mnt}/snapshots/${newsnap}/@ ro true }
define newlink ${dt}${rnd}
if { mkdir -p ${mnt}/links/${newlink} }
if { ln -s ../../snapshots/${newsnap} ${mnt}/links/${newlink}/0 }
if { cp -P ${mnt}/current/0 ${mnt}/links/${newlink}/1 }
if { cp -P ${mnt}/current/1 ${mnt}/links/${newlink}/2 }
if { cp -P ${mnt}/current/2 ${mnt}/links/${newlink}/3 }
if { mkdir -p ${mnt}/next }
if { ln -sfn ./links/${newlink} ${mnt}/next/current }
if { mv ${mnt}/next/current ${mnt}/ }
echo "Switched to the new snapshot"
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/proc }
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/sys }
redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/dev
}
umount ${mnt}
</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /usr/sbin/syscln
# chmod +x /usr/sbin/syscln
# vi /usr/sbin/syscln</pre>

<pre>#!/bin/execlineb -W
unshare --mount
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime,compress=zstd:3 UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline {
find -H ${mnt}/current/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r btrfs subvolume delete
}
foreground { find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -empty -type d -delete }
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
realpath ${mnt}/current
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r -n 1 unlink
}
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -empty -type d -delete
}
umount ${mnt}
</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

Immutable root with atomic upgrades

2022-02-05T22:10:16Z

Mvsn:

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the [[BTRFS|btrfs]] root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root [[BTRFS|btrfs]] volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

Don't forget to add essential services to their respective runlevels:
<pre>rc-update add devfs sysinit
rc-update add dmesg sysinit
rc-update add mdev sysinit
rc-update add hwdrivers sysinit

rc-update add hwclock boot
rc-update add modules boot
rc-update add sysctl boot
rc-update add hostname boot
rc-update add bootmisc boot
rc-update add syslog boot

rc-update add mount-ro shutdown
rc-update add killprocs shutdown
rc-update add savecache shutdown</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports [[BTRFS|btrfs]] and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Check the latest version number of the <code>refind</code> package:
<pre># apk info -X https://dl-cdn.alpinelinux.org/alpine/edge/testing -U refind</pre>
Download the latest version (replace 0.13.2-r3 in the example below) of the <code>refind</code> package:
<pre># wget https://dl-cdn.alpinelinux.org/alpine/edge/testing/x86_64/refind-0.13.2-r3.apk</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># tar -xzf refind-0.13.2-r3.apk
# cp -r usr/share/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> ([[BTRFS|btrfs]] partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the [[BTRFS|btrfs]] partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
{{Note|These examples are implemented using execline and require <code>execline</code> package in the system. These could surely be implemented in POSIX shell, however execline provides number of runtime advantages and is much more readable.}}
<pre># touch /usr/sbin/sysmut
# chmod +x /usr/sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/execlineb -W
unshare --mount
importas -D 0 source 1
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
backtick -E dt {
date -u +%Y%m%d%H%M%S
}
backtick -E rnd {
pipeline { cat /dev/urandom }
pipeline { tr -dc a-zA-Z }
pipeline { fold -w 8 }
head -n 1
}
define newsnap ${dt}${rnd}
if { mkdir -p ${mnt}/snapshots/${newsnap} }
if { btrfs subvolume snapshot ${mnt}/current/${source}/@ ${mnt}/snapshots/${newsnap}/@ }
if {
redirfd -w 1 ${mnt}/snapshots/${newsnap}/@/etc/fstab
sed s#CURRENT_SNAPSHOTS_PATH#/snapshots/${newsnap}#g ${mnt}/fstab
}
if { mount -t proc none ${mnt}/snapshots/${newsnap}/@/proc }
if { mount -t sysfs sys ${mnt}/snapshots/${newsnap}/@/sys }
if { mount -o bind,ro /dev ${mnt}/snapshots/${newsnap}/@/dev }
foreground {
foreground { mount -o bind,ro /etc/resolv.conf ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if {
chroot ${mnt}/snapshots/${newsnap}/@
foreground { mount -a }
foreground { sh }
importas apply ?
foreground { umount -a }
exit ${apply}
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if { btrfs property set -ts ${mnt}/snapshots/${newsnap}/@ ro true }
define newlink ${dt}${rnd}
if { mkdir -p ${mnt}/links/${newlink} }
if { ln -s ../../snapshots/${newsnap} ${mnt}/links/${newlink}/0 }
if { cp -P ${mnt}/current/0 ${mnt}/links/${newlink}/1 }
if { cp -P ${mnt}/current/1 ${mnt}/links/${newlink}/2 }
if { cp -P ${mnt}/current/2 ${mnt}/links/${newlink}/3 }
if { mkdir -p ${mnt}/next }
if { ln -sfn ./links/${newlink} ${mnt}/next/current }
if { mv ${mnt}/next/current ${mnt}/ }
echo "Switched to the new snapshot"
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/proc }
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/sys }
redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/dev
}
umount ${mnt}
</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/execlineb -W
unshare --mount
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime,compress=zstd:3 UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline {
find -H ${mnt}/current/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r btrfs subvolume delete
}
foreground { find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -empty -type d -delete }
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
realpath ${mnt}/current
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r -n 1 unlink
}
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -empty -type d -delete
}
umount ${mnt}
</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

Immutable root with atomic upgrades

2022-02-05T22:07:41Z

Mvsn:

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the [[BTRFS|btrfs]] root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root [[BTRFS|btrfs]] volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

Don't forget to add essential services to their respective runlevels:
<pre>rc-update add devfs sysinit
rc-update add dmesg sysinit
rc-update add mdev sysinit
rc-update add hwdrivers sysinit

rc-update add hwclock boot
rc-update add modules boot
rc-update add sysctl boot
rc-update add hostname boot
rc-update add bootmisc boot
rc-update add syslog boot

rc-update add mount-ro shutdown
rc-update add killprocs shutdown
rc-update add savecache shutdown</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports [[BTRFS|btrfs]] and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Check the latest version number of the <code>refind</code> package:
<pre># apk info -U refind</pre>
Download the latest version (replace 0.13.2-r3 in the example below) of the <code>refind</code> package:
<pre># wget https://dl-cdn.alpinelinux.org/alpine/edge/testing/x86_64/refind-0.13.2-r3.apk</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># tar -xzf refind-0.13.2-r3.apk
# cp -r usr/share/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> ([[BTRFS|btrfs]] partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the [[BTRFS|btrfs]] partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
{{Note|These examples are implemented using execline and require <code>execline</code> package in the system. These could surely be implemented in POSIX shell, however execline provides number of runtime advantages and is much more readable.}}
<pre># touch /usr/sbin/sysmut
# chmod +x /usr/sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/execlineb -W
unshare --mount
importas -D 0 source 1
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
backtick -E dt {
date -u +%Y%m%d%H%M%S
}
backtick -E rnd {
pipeline { cat /dev/urandom }
pipeline { tr -dc a-zA-Z }
pipeline { fold -w 8 }
head -n 1
}
define newsnap ${dt}${rnd}
if { mkdir -p ${mnt}/snapshots/${newsnap} }
if { btrfs subvolume snapshot ${mnt}/current/${source}/@ ${mnt}/snapshots/${newsnap}/@ }
if {
redirfd -w 1 ${mnt}/snapshots/${newsnap}/@/etc/fstab
sed s#CURRENT_SNAPSHOTS_PATH#/snapshots/${newsnap}#g ${mnt}/fstab
}
if { mount -t proc none ${mnt}/snapshots/${newsnap}/@/proc }
if { mount -t sysfs sys ${mnt}/snapshots/${newsnap}/@/sys }
if { mount -o bind,ro /dev ${mnt}/snapshots/${newsnap}/@/dev }
foreground {
foreground { mount -o bind,ro /etc/resolv.conf ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if {
chroot ${mnt}/snapshots/${newsnap}/@
foreground { mount -a }
foreground { sh }
importas apply ?
foreground { umount -a }
exit ${apply}
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if { btrfs property set -ts ${mnt}/snapshots/${newsnap}/@ ro true }
define newlink ${dt}${rnd}
if { mkdir -p ${mnt}/links/${newlink} }
if { ln -s ../../snapshots/${newsnap} ${mnt}/links/${newlink}/0 }
if { cp -P ${mnt}/current/0 ${mnt}/links/${newlink}/1 }
if { cp -P ${mnt}/current/1 ${mnt}/links/${newlink}/2 }
if { cp -P ${mnt}/current/2 ${mnt}/links/${newlink}/3 }
if { mkdir -p ${mnt}/next }
if { ln -sfn ./links/${newlink} ${mnt}/next/current }
if { mv ${mnt}/next/current ${mnt}/ }
echo "Switched to the new snapshot"
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/proc }
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/sys }
redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/dev
}
umount ${mnt}
</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/execlineb -W
unshare --mount
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime,compress=zstd:3 UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline {
find -H ${mnt}/current/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r btrfs subvolume delete
}
foreground { find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -empty -type d -delete }
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
realpath ${mnt}/current
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r -n 1 unlink
}
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -empty -type d -delete
}
umount ${mnt}
</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

Immutable root with atomic upgrades

2022-02-05T22:04:07Z

Mvsn: use refind from repository

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the [[BTRFS|btrfs]] root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root [[BTRFS|btrfs]] volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

Don't forget to add essential services to their respective runlevels:
<pre>rc-update add devfs sysinit
rc-update add dmesg sysinit
rc-update add mdev sysinit
rc-update add hwdrivers sysinit

rc-update add hwclock boot
rc-update add modules boot
rc-update add sysctl boot
rc-update add hostname boot
rc-update add bootmisc boot
rc-update add syslog boot

rc-update add mount-ro shutdown
rc-update add killprocs shutdown
rc-update add savecache shutdown</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports [[BTRFS|btrfs]] and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Checkout the latest version of the refind:
<pre># apk info -U refind</pre>
Download the latest version (replace 0.13.2-r3 in the example below) of the <code>refind</code> package:
<pre>wget https://dl-cdn.alpinelinux.org/alpine/edge/testing/x86_64/refind-0.13.2-r3.apk</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># tar -xzf refind-0.13.2-r3.apk
# cp -r usr/share/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> ([[BTRFS|btrfs]] partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the [[BTRFS|btrfs]] partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
{{Note|These examples are implemented using execline and require <code>execline</code> package in the system. These could surely be implemented in POSIX shell, however execline provides number of runtime advantages and is much more readable.}}
<pre># touch /usr/sbin/sysmut
# chmod +x /usr/sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/execlineb -W
unshare --mount
importas -D 0 source 1
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
backtick -E dt {
date -u +%Y%m%d%H%M%S
}
backtick -E rnd {
pipeline { cat /dev/urandom }
pipeline { tr -dc a-zA-Z }
pipeline { fold -w 8 }
head -n 1
}
define newsnap ${dt}${rnd}
if { mkdir -p ${mnt}/snapshots/${newsnap} }
if { btrfs subvolume snapshot ${mnt}/current/${source}/@ ${mnt}/snapshots/${newsnap}/@ }
if {
redirfd -w 1 ${mnt}/snapshots/${newsnap}/@/etc/fstab
sed s#CURRENT_SNAPSHOTS_PATH#/snapshots/${newsnap}#g ${mnt}/fstab
}
if { mount -t proc none ${mnt}/snapshots/${newsnap}/@/proc }
if { mount -t sysfs sys ${mnt}/snapshots/${newsnap}/@/sys }
if { mount -o bind,ro /dev ${mnt}/snapshots/${newsnap}/@/dev }
foreground {
foreground { mount -o bind,ro /etc/resolv.conf ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if {
chroot ${mnt}/snapshots/${newsnap}/@
foreground { mount -a }
foreground { sh }
importas apply ?
foreground { umount -a }
exit ${apply}
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if { btrfs property set -ts ${mnt}/snapshots/${newsnap}/@ ro true }
define newlink ${dt}${rnd}
if { mkdir -p ${mnt}/links/${newlink} }
if { ln -s ../../snapshots/${newsnap} ${mnt}/links/${newlink}/0 }
if { cp -P ${mnt}/current/0 ${mnt}/links/${newlink}/1 }
if { cp -P ${mnt}/current/1 ${mnt}/links/${newlink}/2 }
if { cp -P ${mnt}/current/2 ${mnt}/links/${newlink}/3 }
if { mkdir -p ${mnt}/next }
if { ln -sfn ./links/${newlink} ${mnt}/next/current }
if { mv ${mnt}/next/current ${mnt}/ }
echo "Switched to the new snapshot"
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/proc }
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/sys }
redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/dev
}
umount ${mnt}
</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/execlineb -W
unshare --mount
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime,compress=zstd:3 UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline {
find -H ${mnt}/current/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r btrfs subvolume delete
}
foreground { find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -empty -type d -delete }
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
realpath ${mnt}/current
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r -n 1 unlink
}
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -empty -type d -delete
}
umount ${mnt}
</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

Immutable root with atomic upgrades

2022-01-31T20:09:37Z

Mvsn: add service reminder

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks [[BTRFS|btrfs]] driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the [[BTRFS|btrfs]] root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root [[BTRFS|btrfs]] volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

Don't forget to add essential services to their respective runlevels:
<pre>rc-update add devfs sysinit
rc-update add dmesg sysinit
rc-update add mdev sysinit
rc-update add hwdrivers sysinit

rc-update add hwclock boot
rc-update add modules boot
rc-update add sysctl boot
rc-update add hostname boot
rc-update add bootmisc boot
rc-update add syslog boot

rc-update add mount-ro shutdown
rc-update add killprocs shutdown
rc-update add savecache shutdown</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports [[BTRFS|btrfs]] and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> ([[BTRFS|btrfs]] partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the [[BTRFS|btrfs]] partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
{{Note|These examples are implemented using execline and require <code>execline</code> package in the system. These could surely be implemented in POSIX shell, however execline provides number of runtime advantages and is much more readable.}}
<pre># touch /usr/sbin/sysmut
# chmod +x /usr/sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/execlineb -W
unshare --mount
importas -D 0 source 1
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
backtick -E dt {
date -u +%Y%m%d%H%M%S
}
backtick -E rnd {
pipeline { cat /dev/urandom }
pipeline { tr -dc a-zA-Z }
pipeline { fold -w 8 }
head -n 1
}
define newsnap ${dt}${rnd}
if { mkdir -p ${mnt}/snapshots/${newsnap} }
if { btrfs subvolume snapshot ${mnt}/current/${source}/@ ${mnt}/snapshots/${newsnap}/@ }
if {
redirfd -w 1 ${mnt}/snapshots/${newsnap}/@/etc/fstab
sed s#CURRENT_SNAPSHOTS_PATH#/snapshots/${newsnap}#g ${mnt}/fstab
}
if { mount -t proc none ${mnt}/snapshots/${newsnap}/@/proc }
if { mount -t sysfs sys ${mnt}/snapshots/${newsnap}/@/sys }
if { mount -o bind,ro /dev ${mnt}/snapshots/${newsnap}/@/dev }
foreground {
foreground { mount -o bind,ro /etc/resolv.conf ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if {
chroot ${mnt}/snapshots/${newsnap}/@
foreground { mount -a }
foreground { sh }
importas apply ?
foreground { umount -a }
exit ${apply}
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if { btrfs property set -ts ${mnt}/snapshots/${newsnap}/@ ro true }
define newlink ${dt}${rnd}
if { mkdir -p ${mnt}/links/${newlink} }
if { ln -s ../../snapshots/${newsnap} ${mnt}/links/${newlink}/0 }
if { cp -P ${mnt}/current/0 ${mnt}/links/${newlink}/1 }
if { cp -P ${mnt}/current/1 ${mnt}/links/${newlink}/2 }
if { cp -P ${mnt}/current/2 ${mnt}/links/${newlink}/3 }
if { mkdir -p ${mnt}/next }
if { ln -sfn ./links/${newlink} ${mnt}/next/current }
if { mv ${mnt}/next/current ${mnt}/ }
echo "Switched to the new snapshot"
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/proc }
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/sys }
redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/dev
}
umount ${mnt}
</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/execlineb -W
unshare --mount
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime,compress=zstd:3 UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline {
find -H ${mnt}/current/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r btrfs subvolume delete
}
foreground { find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -empty -type d -delete }
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
realpath ${mnt}/current
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r -n 1 unlink
}
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -empty -type d -delete
}
umount ${mnt}
</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

Immutable root with atomic upgrades

2022-01-31T20:02:40Z

Mvsn: more robust syscln script

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks [[BTRFS|btrfs]] driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the [[BTRFS|btrfs]] root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root [[BTRFS|btrfs]] volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports [[BTRFS|btrfs]] and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> ([[BTRFS|btrfs]] partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the [[BTRFS|btrfs]] partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
{{Note|These examples are implemented using execline and require <code>execline</code> package in the system. These could surely be implemented in POSIX shell, however execline provides number of runtime advantages and is much more readable.}}
<pre># touch /usr/sbin/sysmut
# chmod +x /usr/sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/execlineb -W
unshare --mount
importas -D 0 source 1
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
backtick -E dt {
date -u +%Y%m%d%H%M%S
}
backtick -E rnd {
pipeline { cat /dev/urandom }
pipeline { tr -dc a-zA-Z }
pipeline { fold -w 8 }
head -n 1
}
define newsnap ${dt}${rnd}
if { mkdir -p ${mnt}/snapshots/${newsnap} }
if { btrfs subvolume snapshot ${mnt}/current/${source}/@ ${mnt}/snapshots/${newsnap}/@ }
if {
redirfd -w 1 ${mnt}/snapshots/${newsnap}/@/etc/fstab
sed s#CURRENT_SNAPSHOTS_PATH#/snapshots/${newsnap}#g ${mnt}/fstab
}
if { mount -t proc none ${mnt}/snapshots/${newsnap}/@/proc }
if { mount -t sysfs sys ${mnt}/snapshots/${newsnap}/@/sys }
if { mount -o bind,ro /dev ${mnt}/snapshots/${newsnap}/@/dev }
foreground {
foreground { mount -o bind,ro /etc/resolv.conf ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if {
chroot ${mnt}/snapshots/${newsnap}/@
foreground { mount -a }
foreground { sh }
importas apply ?
foreground { umount -a }
exit ${apply}
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if { btrfs property set -ts ${mnt}/snapshots/${newsnap}/@ ro true }
define newlink ${dt}${rnd}
if { mkdir -p ${mnt}/links/${newlink} }
if { ln -s ../../snapshots/${newsnap} ${mnt}/links/${newlink}/0 }
if { cp -P ${mnt}/current/0 ${mnt}/links/${newlink}/1 }
if { cp -P ${mnt}/current/1 ${mnt}/links/${newlink}/2 }
if { cp -P ${mnt}/current/2 ${mnt}/links/${newlink}/3 }
if { mkdir -p ${mnt}/next }
if { ln -sfn ./links/${newlink} ${mnt}/next/current }
if { mv ${mnt}/next/current ${mnt}/ }
echo "Switched to the new snapshot"
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/proc }
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/sys }
redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/dev
}
umount ${mnt}
</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/execlineb -W
unshare --mount
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime,compress=zstd:3 UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline {
find -H ${mnt}/current/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r btrfs subvolume delete
}
foreground { find -H ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -empty -type d -delete }
foreground {
pipeline {
foreground {
pipeline {
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -print0
}
xargs -0 -r realpath
}
realpath ${mnt}/current
}
pipeline { tr \\n \\0 }
pipeline { sort -z }
pipeline { uniq -u -z }
pipeline { xargs -0 -r -n 1 -I [] find -H [] -maxdepth 1 -mindepth 1 -print0 }
xargs -0 -r -n 1 unlink
}
find -H ${mnt}/links/ -maxdepth 1 -mindepth 1 -empty -type d -delete
}
umount ${mnt}
</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

Immutable root with atomic upgrades

2022-01-28T22:06:34Z

Mvsn: execline upgrade scripts instead of shell

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and [[BTRFS|btrfs]].

=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks [[BTRFS|btrfs]] driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the [[BTRFS|btrfs]] root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root [[BTRFS|btrfs]] volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports [[BTRFS|btrfs]] and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> ([[BTRFS|btrfs]] partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the [[BTRFS|btrfs]] partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
{{Note|These examples are implemented using execline and require <code>execline</code> package in the system. These could surely be implemented in POSIX shell, however execline provides number of runtime advantages and is much more readable.}}
<pre># touch /usr/sbin/sysmut
# chmod +x /usr/sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/execlineb -W
unshare --mount
importas -D 0 source 1
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
backtick -E dt {
date -u +%Y%m%d%H%M%S
}
backtick -E rnd {
pipeline { cat /dev/urandom }
pipeline { tr -dc a-zA-Z }
pipeline { fold -w 8 }
head -n 1
}
define newsnap ${dt}${rnd}
if { mkdir -p ${mnt}/snapshots/${newsnap} }
if { btrfs subvolume snapshot ${mnt}/current/${source}/@ ${mnt}/snapshots/${newsnap}/@ }
if {
redirfd -w 1 ${mnt}/snapshots/${newsnap}/@/etc/fstab
sed s#CURRENT_SNAPSHOTS_PATH#/snapshots/${newsnap}#g ${mnt}/fstab
}
if { mount -t proc none ${mnt}/snapshots/${newsnap}/@/proc }
if { mount -t sysfs sys ${mnt}/snapshots/${newsnap}/@/sys }
if { mount -o bind,ro /dev ${mnt}/snapshots/${newsnap}/@/dev }
foreground {
foreground { mount -o bind,ro /etc/resolv.conf ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if {
chroot ${mnt}/snapshots/${newsnap}/@
foreground { mount -a }
foreground { sh }
importas apply ?
foreground { umount -a }
exit ${apply}
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/etc/resolv.conf }
if { btrfs property set -ts ${mnt}/snapshots/${newsnap}/@ ro true }
define newlink ${dt}${rnd}
if { mkdir -p ${mnt}/links/${newlink} }
if { ln -s ../../snapshots/${newsnap} ${mnt}/links/${newlink}/0 }
if { cp -P ${mnt}/current/0 ${mnt}/links/${newlink}/1 }
if { cp -P ${mnt}/current/1 ${mnt}/links/${newlink}/2 }
if { cp -P ${mnt}/current/2 ${mnt}/links/${newlink}/3 }
if { mkdir -p ${mnt}/next }
if { ln -sfn ./links/${newlink} ${mnt}/next/current }
if { mv ${mnt}/next/current ${mnt}/ }
echo "Switched to the new snapshot"
}
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/proc }
foreground { redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/sys }
redirfd -w 2 /dev/null umount ${mnt}/snapshots/${newsnap}/@/dev
}
umount ${mnt}
</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/execlineb -W
unshare --mount
define mnt /media/root
if { mkdir -p ${mnt} }
if { mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 ${mnt} }
foreground {
foreground {
pipeline {
foreground {
find ${mnt}/snapshots/ -maxdepth 1 -mindepth 1
}
pipeline {
find ${mnt}/current/ -maxdepth 1 -mindepth 1
}
xargs -r -n 1 readlink -f
}
pipeline { sort }
pipeline { uniq -u }
pipeline { xargs -r -n 1 -I [] find [] -maxdepth 1 -mindepth 1 }
xargs -r btrfs subvolume delete
}
foreground { find ${mnt}/snapshots/ -maxdepth 1 -mindepth 1 -empty -type d -delete }
foreground {
pipeline {
foreground {
find ${mnt}/links/ -maxdepth 1 -mindepth 1
}
readlink -f ${mnt}/current
}
pipeline { sort }
pipeline { uniq -u }
pipeline { xargs -r -n 1 -I [] find [] -maxdepth 1 -mindepth 1 }
xargs -r -n 1 unlink
}
find ${mnt}/links/ -maxdepth 1 -mindepth 1 -empty -type d -delete
}
umount ${mnt}
</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

Immutable root with atomic upgrades

2021-12-19T21:57:40Z

Mvsn:

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshots" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root"
mkdir -p "$ROOTVOLMNT"
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT"

SNAPSHOTS=$({ \
find "$ROOTVOLMNT/snapshots/" -maxdepth 1 -mindepth 1
find "$ROOTVOLMNT/current/" -maxdepth 1 -mindepth 1 \
| xargs -n 1 readlink -f
} | sort | uniq -u)

if [ -z "$SNAPSHOTS" ]; then
echo "Nothing to remove"
else
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 -n 1 -I {} find {} -maxdepth 1 -mindepth 1 \
| tr \\n \\0 \
| xargs -r -0 btrfs subvolume delete
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 rm -r
fi

umount "$ROOTVOLMNT"</pre>

= Allowing temporary runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

Immutable root with atomic upgrades

2021-12-19T21:56:15Z

Mvsn: Add overlaytmpfs info

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshots" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root"
mkdir -p "$ROOTVOLMNT"
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT"

SNAPSHOTS=$({ \
find "$ROOTVOLMNT/snapshots/" -maxdepth 1 -mindepth 1
find "$ROOTVOLMNT/current/" -maxdepth 1 -mindepth 1 \
| xargs -n 1 readlink -f
} | sort | uniq -u)

if [ -z "$SNAPSHOTS" ]; then
echo "Nothing to remove"
else
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 -n 1 -I {} find {} -maxdepth 1 -mindepth 1 \
| tr \\n \\0 \
| xargs -r -0 btrfs subvolume delete
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 rm -r
fi

umount "$ROOTVOLMNT"</pre>

= Allowing temporal runtime alterations =
You can use <code>overlayfs</code> with <code>tmpfs</code> built into Alpine's init script to allow changes in the rootfs which will be automatically reverted upon reboot. 
To make use this just add <code>overlaytmpfs</code> to the kernel boot options in <code>refind.conf</code>, e.g.:
<pre>
...
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@,ro,noatime resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 overlaytmpfs quiet splash"

submenuentry "Boot fallback 1" {
...
</pre>

Immutable root with atomic upgrades

2021-12-19T21:44:57Z

Mvsn:

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "$SNP/etc/fstab"

# cp -L /etc/resolv.conf "$SNP/etc/"
# chroot "$SNP" /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshots" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root"
mkdir -p "$ROOTVOLMNT"
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT"

SNAPSHOTS=$({ \
find "$ROOTVOLMNT/snapshots/" -maxdepth 1 -mindepth 1
find "$ROOTVOLMNT/current/" -maxdepth 1 -mindepth 1 \
| xargs -n 1 readlink -f
} | sort | uniq -u)

if [ -z "$SNAPSHOTS" ]; then
echo "Nothing to remove"
else
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 -n 1 -I {} find {} -maxdepth 1 -mindepth 1 \
| tr \\n \\0 \
| xargs -r -0 btrfs subvolume delete
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 rm -r
fi

umount "$ROOTVOLMNT"</pre>

Immutable root with atomic upgrades

2021-09-03T07:47:37Z

Mvsn:

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "/mnt/snapshots/20210411212549sdBXyLxg/@/etc/fstab"

# cp -L /etc/resolv.conf /mnt/etc/
# chroot /mnt /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshots" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root"
mkdir -p "$ROOTVOLMNT"
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT"

SNAPSHOTS=$({ \
find "$ROOTVOLMNT/snapshots/" -maxdepth 1 -mindepth 1
find "$ROOTVOLMNT/current/" -maxdepth 1 -mindepth 1 \
| xargs -n 1 readlink -f
} | sort | uniq -u)

if [ -z "$SNAPSHOTS" ]; then
echo "Nothing to remove"
else
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 -n 1 -I {} find {} -maxdepth 1 -mindepth 1 \
| tr \\n \\0 \
| xargs -r -0 btrfs subvolume delete
printf %s\\n "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 rm -r
fi

umount "$ROOTVOLMNT"</pre>

Immutable root with atomic upgrades

2021-09-02T07:02:52Z

Mvsn:

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "/mnt/snapshots/20210411212549sdBXyLxg/@/etc/fstab"

# cp -L /etc/resolv.conf /mnt/etc/
# chroot /mnt /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshots" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root"
mkdir -p "$ROOTVOLMNT"
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT"

SNAPSHOTS=$({ \
find "$ROOTVOLMNT/snapshots/" -maxdepth 1 -mindepth 1
find "$ROOTVOLMNT/current/" -maxdepth 1 -mindepth 1 \
| xargs -n 1 readlink -f
} | sort | uniq -u)

if [ -z "$SNAPSHOTS" ]; then
echo "Nothing to remove"
else
echo "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 -n 1 -I {} find {} -maxdepth 1 -mindepth 1 \
| tr \\n \\0 \
| xargs -r -0 btrfs subvolume delete
echo "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 rm -r
fi

umount "$ROOTVOLMNT"</pre>

Immutable root with atomic upgrades

2021-09-02T07:00:51Z

Mvsn:

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/snapshots/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/snapshots/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "/mnt/snapshots/20210411212549sdBXyLxg/@/etc/fstab"

# cp -L /etc/resolv.conf /mnt/etc/
# chroot /mnt /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshots" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root"
mkdir -p "$ROOTVOLMNT"
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT"

SNAPSHOTS=$({ \
find "$ROOTVOLMNT/snapshots/" -maxdepth 1 -mindepth 1
find "$ROOTVOLMNT/current/" -maxdepth 1 -mindepth 1 \
| xargs -n 1 readlink -f
} | sort | uniq -u)

if [ -z "$SNAPSHOTS" ]; then
echo "Nothing to remove"
else
echo "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 -n 1 -I {} find {} -maxdepth 1 -mindepth 1 \
| tr \\n \\0 \
| xargs -r -0 btrfs subvolume delete
echo "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 rm -r
fi

umount "$ROOTVOLMNT"</pre>

Immutable root with atomic upgrades

2021-07-10T15:46:24Z

Mvsn:

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "/mnt/snapshots/20210411212549sdBXyLxg/@/etc/fstab"

# cp -L /etc/resolv.conf /mnt/etc/
# chroot /mnt /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOT_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshots" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root"
mkdir -p "$ROOTVOLMNT"
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT"

SNAPSHOTS=$({ \
find "$ROOTVOLMNT/snapshots/" -maxdepth 1 -mindepth 1
find "$ROOTVOLMNT/current/" -maxdepth 1 -mindepth 1 \
| xargs -n 1 readlink -f
} | sort | uniq -u)

if [ -z "$SNAPSHOTS" ]; then
echo "Nothing to remove"
else
echo "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 -n 1 -I {} find {} -maxdepth 1 -mindepth 1 \
| tr \\n \\0 \
| xargs -r -0 btrfs subvolume delete
echo "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 rm -r
fi

umount "$ROOTVOLMNT"</pre>

Immutable root with atomic upgrades

2021-07-10T15:44:55Z

Mvsn:

{|style="width: 33em; padding:2px; margin:0; margin-bottom:10px; background-color:#f6f6f6; border:1px solid #aaa; -moz-border-radius-bottomright: 0.5em; -moz-border-radius-bottomleft: 1em; border-radius-bottomright: 0.5em; border-radius-bottomleft: 1em; -webkit-border-bottom-right-radius: 0.5em; -webkit-border-bottom-left-radius: 1em;"
|<div style="font-size: 1.5em; font-weight:bold;"> [[Image:Underconstruction_clock_icon_gray.svg‎|64px|left|link=]] This page is a work in progress ... </div>This page is still being developed.
|}

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -t sysfs sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "/mnt/snapshots/20210411212549sdBXyLxg/@/etc/fstab"

# cp -L /etc/resolv.conf /mnt/etc/
# chroot /mnt /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOT_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshots" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root"
mkdir -p "$ROOTVOLMNT"
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT"

SNAPSHOTS=$({ \
find "$ROOTVOLMNT/snapshots/" -maxdepth 1 -mindepth 1
find "$ROOTVOLMNT/current/" -maxdepth 1 -mindepth 1 \
| xargs -n 1 readlink -f
} | sort | uniq -u)

if [ -z "$SNAPSHOTS" ]; then
echo "Nothing to remove"
else
echo "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 -n 1 -I {} find {} -maxdepth 1 -mindepth 1 \
| tr \\n \\0 \
| xargs -r -0 btrfs subvolume delete
echo "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 rm -r
fi

umount "$ROOTVOLMNT"</pre>

Immutable root with atomic upgrades

2021-07-10T15:42:29Z

Mvsn:

{|style="width: 33em; padding:2px; margin:0; margin-bottom:10px; background-color:#f6f6f6; border:1px solid #aaa; -moz-border-radius-bottomright: 0.5em; -moz-border-radius-bottomleft: 1em; border-radius-bottomright: 0.5em; border-radius-bottomleft: 1em; -webkit-border-bottom-right-radius: 0.5em; -webkit-border-bottom-left-radius: 1em;"
|<div style="font-size: 1.5em; font-weight:bold;"> [[Image:Underconstruction_clock_icon_gray.svg‎|64px|left|link=]] This page is a work in progress ... </div>This page is still being developed.
|}

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -o bind /sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "/mnt/snapshots/20210411212549sdBXyLxg/@/etc/fstab"

# cp -L /etc/resolv.conf /mnt/etc/
# chroot /mnt /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOT_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshots" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root"
mkdir -p "$ROOTVOLMNT"
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT"

SNAPSHOTS=$({ \
find "$ROOTVOLMNT/snapshots/" -maxdepth 1 -mindepth 1
find "$ROOTVOLMNT/current/" -maxdepth 1 -mindepth 1 \
| xargs -n 1 readlink -f
} | sort | uniq -u)

if [ -z "$SNAPSHOTS" ]; then
echo "Nothing to remove"
else
echo "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 -n 1 -I {} find {} -maxdepth 1 -mindepth 1 \
| tr \\n \\0 \
| xargs -r -0 btrfs subvolume delete
echo "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 rm -r
fi

umount "$ROOTVOLMNT"</pre>

Immutable root with atomic upgrades

2021-07-10T15:40:37Z

Mvsn:

{|style="width: 33em; padding:2px; margin:0; margin-bottom:10px; background-color:#f6f6f6; border:1px solid #aaa; -moz-border-radius-bottomright: 0.5em; -moz-border-radius-bottomleft: 1em; border-radius-bottomright: 0.5em; border-radius-bottomleft: 1em; -webkit-border-bottom-right-radius: 0.5em; -webkit-border-bottom-left-radius: 1em;"
|<div style="font-size: 1.5em; font-weight:bold;"> [[Image:Underconstruction_clock_icon_gray.svg‎|64px|left|link=]] This page is a work in progress ... </div>This page is still being developed.
|}

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -o bind /sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "/mnt/snapshots/20210411212549sdBXyLxg/@/etc/fstab"

# cp -L /etc/resolv.conf /mnt/etc/
# chroot /mnt /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

Example script to mutate the the system:

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOT_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshots" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

It will get you into the root shell chrooted into the new snapshot, where you can apply any change you like. 
If chroot shell exits with an error, there will be no switch to the new snapshots. This means you can manually discard changes while in the chroot by:

<pre># exit 1</pre>

= Deleting unused snapshots =
Unused snapshots can be garbage-collected by:

<pre># touch /sbin/syscln
# chmod +x /sbin/syscln
# vi /sbin/syscln</pre>

<pre>#!/bin/sh
ROOTVOLMNT="/vol/root"
mkdir -p "$ROOTVOLMNT"
mount -t btrfs -o rw,noatime UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 "$ROOTVOLMNT"

SNAPSHOTS=$({
find "$ROOTVOLMNT/snapshots/" -maxdepth 1 -mindepth 1
find "$ROOTVOLMNT/current/" -maxdepth 1 -mindepth 1 \
| xargs -n 1 readlink -f
} | sort | uniq -u)

if [ -z "$SNAPSHOTS" ]; then
echo "Nothing to remove"
else
echo "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 -n 1 -I {} find {} -maxdepth 1 -mindepth 1 \
| tr \\n \\0 \
| xargs -r -0 btrfs subvolume delete
echo "$SNAPSHOTS" \
| tr \\n \\0 \
| xargs -r -0 rm -r
fi

umount "$ROOTVOLMNT"</pre>

Immutable root with atomic upgrades

2021-07-10T13:27:30Z

Mvsn:

{|style="width: 33em; padding:2px; margin:0; margin-bottom:10px; background-color:#f6f6f6; border:1px solid #aaa; -moz-border-radius-bottomright: 0.5em; -moz-border-radius-bottomleft: 1em; border-radius-bottomright: 0.5em; border-radius-bottomleft: 1em; -webkit-border-bottom-right-radius: 0.5em; -webkit-border-bottom-left-radius: 1em;"
|<div style="font-size: 1.5em; font-weight:bold;"> [[Image:Underconstruction_clock_icon_gray.svg‎|64px|left|link=]] This page is a work in progress ... </div>This page is still being developed.
|}

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -o bind /sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "/mnt/snapshots/20210411212549sdBXyLxg/@/etc/fstab"

# cp -L /etc/resolv.conf /mnt/etc/
# chroot /mnt /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
Example script to change the the system:

<pre># touch /sbin/sysmut
# chmod +x /sbin/sysmut
# vi /sbin/sysmut</pre>

<pre>ROOTVOLMNT="/vol/root" && \
mkdir -p "$ROOTVOLMNT" && \
mount -t btrfs -o rw,noatime UUID=b9fa2e7b-e128-4e64-861a-3ee1d33d0676 "$ROOTVOLMNT" && \
NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS" && \
btrfs subvolume snapshot "$ROOTVOLMNT/current/0/@" "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" && \
sed "s#CURRENT_SNAPSHOT_PATH#/snapshots/$NEWSNAPSHOTS#g" "$ROOTVOLMNT/fstab" > "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/etc/fstab" && \
mount -t proc none "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/proc" && \
mount -t sysfs sys "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/sys" && \
mount -o bind /dev "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@/dev" && \
chroot "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" /bin/sh -c 'mount -a; sh; APPLY=$?; umount -a; exit $APPLY' && \
btrfs property set -ts "$ROOTVOLMNT/snapshots/$NEWSNAPSHOTS/@" ro true && \
NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)" && \
mkdir -p "$ROOTVOLMNT/links/$NEWLINKS" && \
ln -s "../../snapshots/$NEWSNAPSHOTS" "$ROOTVOLMNT/links/$NEWLINKS/0" && \
cp -P "$ROOTVOLMNT/current/0" "$ROOTVOLMNT/links/$NEWLINKS/1" && \
cp -P "$ROOTVOLMNT/current/1" "$ROOTVOLMNT/links/$NEWLINKS/2" && \
cp -P "$ROOTVOLMNT/current/2" "$ROOTVOLMNT/links/$NEWLINKS/3" && \
mkdir -p "$ROOTVOLMNT/next" && \
ln -sfn "./links/$NEWLINKS" "$ROOTVOLMNT/next/current" && \
mv "$ROOTVOLMNT/next/current" "$ROOTVOLMNT/" \
&& echo "Switched to the new snapshot" \
|| echo "Changes discarded"
umount "$ROOTVOLMNT"</pre>

Immutable root with atomic upgrades

2021-07-10T12:15:06Z

Mvsn:

{|style="width: 33em; padding:2px; margin:0; margin-bottom:10px; background-color:#f6f6f6; border:1px solid #aaa; -moz-border-radius-bottomright: 0.5em; -moz-border-radius-bottomleft: 1em; border-radius-bottomright: 0.5em; border-radius-bottomleft: 1em; -webkit-border-bottom-right-radius: 0.5em; -webkit-border-bottom-left-radius: 1em;"
|<div style="font-size: 1.5em; font-weight:bold;"> [[Image:Underconstruction_clock_icon_gray.svg‎|64px|left|link=]] This page is a work in progress ... </div>This page is still being developed.
|}

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -o bind /sys $SNP/sys

# sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "/mnt/snapshots/20210411212549sdBXyLxg/@/etc/fstab"

# cp -L /etc/resolv.conf /mnt/etc/
# chroot /mnt /bin/sh

# mount -a

# mv /etc/resolv.conf /tmp/
# ln -s /tmp/resolv.conf /etc/resolv.conf</pre>

As soon as you in chroot, define repositories:
<pre># echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># umount -a
# exit</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
{{Todo|}}

Immutable root with atomic upgrades

2021-06-19T21:45:47Z

Mvsn:

{|style="width: 33em; padding:2px; margin:0; margin-bottom:10px; background-color:#f6f6f6; border:1px solid #aaa; -moz-border-radius-bottomright: 0.5em; -moz-border-radius-bottomleft: 1em; border-radius-bottomright: 0.5em; border-radius-bottomleft: 1em; -webkit-border-bottom-right-radius: 0.5em; -webkit-border-bottom-left-radius: 1em;"
|<div style="font-size: 1.5em; font-weight:bold;"> [[Image:Underconstruction_clock_icon_gray.svg‎|64px|left|link=]] This page is a work in progress ... </div>This page is still being developed.
|}

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -o bind /sys $SNP/sys

# mkdir -p $SNP/var/tmp
# mount -o bind /mnt/commons/@var@tmp $SNP/var/tmp

# mkdir -p $SNP/var/cache
# mount -o bind /mnt/commons/@var@cache $SNP/var/cache

# mkdir -p $SNP/var/log
# mount -o bind /mnt/commons/@var@log $SNP/var/log

# mkdir -p $SNP/var/lib/flatpak
# mount -o bind /mnt/commons/@var@lib@flatpak $SNP/var/lib/flatpak

# mkdir -p $SNP/var/lib/iwd
# mount -o bind /mnt/commons/@var@lib@iwd $SNP/var/lib/iwd

# mkdir -p $SNP/home
# mount -o bind /mnt/commons/@home $SNP/home

# cp -L /etc/resolv.conf /mnt/etc/
# chroot /mnt /bin/sh</pre>

As soon as you in chroot, define repositories:
<pre># mkdir -p /etc/apk
# echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

Now, configure the system, start with setting a password for the root:
<pre># passwd root</pre>

With the snapshot prepared and configured we can chroot out of it and unmount everything:
<pre># exit
# umount $SNP/dev
# umount $SNP/proc
# umount $SNP/sys

# umount $SNP/var/tmp

# umount $SNP/var/cache

# umount $SNP/var/log

# umount $SNP/var/lib/flatpak

# umount $SNP/var/lib/iwd

# umount $SNP/home</pre>

...and inject fstab:
<pre># sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "/mnt/snapshots/20210411212549sdBXyLxg/@/etc/fstab"</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
{{Todo|}}

Immutable root with atomic upgrades

2021-06-19T21:24:33Z

Mvsn:

{|style="width: 33em; padding:2px; margin:0; margin-bottom:10px; background-color:#f6f6f6; border:1px solid #aaa; -moz-border-radius-bottomright: 0.5em; -moz-border-radius-bottomleft: 1em; border-radius-bottomright: 0.5em; border-radius-bottomleft: 1em; -webkit-border-bottom-right-radius: 0.5em; -webkit-border-bottom-left-radius: 1em;"
|<div style="font-size: 1.5em; font-weight:bold;"> [[Image:Underconstruction_clock_icon_gray.svg‎|64px|left|link=]] This page is a work in progress ... </div>This page is still being developed.
|}

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Include anything else in <code>/var</code> that should be mutable, for example:
<pre># btrfs subvolume create /mnt/commons/@var@lib@iwd</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/iwd btrfs subvol=/commons/@var@lib@iwd,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@var@lib@iwd
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -o bind /sys $SNP/sys

# mkdir -p $SNP/var/tmp
# mount -o bind /mnt/commons/@var@tmp $SNP/var/tmp

# mkdir -p $SNP/var/cache
# mount -o bind /mnt/commons/@var@cache $SNP/var/cache

# mkdir -p $SNP/var/log
# mount -o bind /mnt/commons/@var@log $SNP/var/log

# mkdir -p $SNP/var/lib/flatpak
# mount -o bind /mnt/commons/@var@lib@flatpak $SNP/var/lib/flatpak

# mkdir -p $SNP/var/lib/iwd
# mount -o bind /mnt/commons/@var@lib@iwd $SNP/var/lib/iwd

# mkdir -p $SNP/home
# mount -o bind /mnt/commons/@home $SNP/home

# cp -L /etc/resolv.conf /mnt/etc/
# chroot /mnt /bin/sh</pre>

As soon as you in chroot, define repositories:
<pre># mkdir -p /etc/apk
# echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install any suitable networking software, like <code>iwd</code> in this example, so you will not end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

With the snapshot prepared we can chroot out of it and unmount everything:
<pre># exit
# umount $SNP/dev
# umount $SNP/proc
# umount $SNP/sys

# umount $SNP/var/tmp

# umount $SNP/var/cache

# umount $SNP/var/log

# umount $SNP/var/lib/flatpak

# umount $SNP/var/lib/iwd

# umount $SNP/home</pre>

...and inject fstab:
<pre># sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "/mnt/snapshots/20210411212549sdBXyLxg/@/etc/fstab"</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
{{Todo|}}

Immutable root with atomic upgrades

2021-06-19T21:05:57Z

Mvsn:

{|style="width: 33em; padding:2px; margin:0; margin-bottom:10px; background-color:#f6f6f6; border:1px solid #aaa; -moz-border-radius-bottomright: 0.5em; -moz-border-radius-bottomleft: 1em; border-radius-bottomright: 0.5em; border-radius-bottomleft: 1em; -webkit-border-bottom-right-radius: 0.5em; -webkit-border-bottom-left-radius: 1em;"
|<div style="font-size: 1.5em; font-weight:bold;"> [[Image:Underconstruction_clock_icon_gray.svg‎|64px|left|link=]] This page is a work in progress ... </div>This page is still being developed.
|}

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -o bind /sys $SNP/sys

# mkdir -p $SNP/var/tmp
# mount -o bind /mnt/commons/@var@tmp $SNP/var/tmp

# mkdir -p $SNP/var/cache
# mount -o bind /mnt/commons/@var@cache $SNP/var/cache

# mkdir -p $SNP/var/log
# mount -o bind /mnt/commons/@var@log $SNP/var/log

# mkdir -p $SNP/var/lib/flatpak
# mount -o bind /mnt/commons/@var@lib@flatpak $SNP/var/lib/flatpak

# mkdir -p $SNP/home
# mount -o bind /mnt/commons/@home $SNP/home

# cp -L /etc/resolv.conf /mnt/etc/
# chroot /mnt /bin/sh</pre>

As soon as you in chroot, define repositories:
<pre># mkdir -p /etc/apk
# echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install and configure any suitable networking software, like <code>iwd</code>, so you won't end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

With the snapshot prepared we can chroot out of it and unmount everything:
<pre># exit
# umount $SNP/dev
# umount $SNP/proc
# umount $SNP/sys

# umount $SNP/var/tmp

# umount $SNP/var/cache

# umount $SNP/var/log

# umount $SNP/var/lib/flatpak

# umount $SNP/home</pre>

...and inject fstab:
<pre># sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "/mnt/snapshots/20210411212549sdBXyLxg/@/etc/fstab"</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file, remember to replace example UUIDs with your own for <code>root</code> (btrfs partition) and <code>resume</code> (swap partition):
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/0/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/1/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/2/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "root=UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 rootfstype=btrfs rootflags=subvol=/current/3/@ resume=UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 ro,noatime quiet splash"
}
}</pre>
{{Note|<code>"ROOT"</code> is the <code>PARTLABEL</code> of the btrfs partition. You may also use <code>PARTUUID</code> instead. To get both <code>blkid</code> from <code>blkid</code> package can be used. <code>blkid</code> included in busybox does not provide this information. }}
To add rEFInd to UEFI, <code>efibootmgr</code> is a suitable tool:
<pre># apk add efibootmgr
# efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd" --verbose</pre>
<code>/dev/sda</code> is our disk device and <code>1</code> is the number of partition containing <code>rEFInd</code>.

= Updating or altering the system =
{{Todo|}}

Immutable root with atomic upgrades

2021-06-05T13:24:11Z

Mvsn:

{|style="width: 33em; padding:2px; margin:0; margin-bottom:10px; background-color:#f6f6f6; border:1px solid #aaa; -moz-border-radius-bottomright: 0.5em; -moz-border-radius-bottomleft: 1em; border-radius-bottomright: 0.5em; border-radius-bottomleft: 1em; -webkit-border-bottom-right-radius: 0.5em; -webkit-border-bottom-left-radius: 1em;"
|<div style="font-size: 1.5em; font-weight:bold;"> [[Image:Underconstruction_clock_icon_gray.svg‎|64px|left|link=]] This page is a work in progress ... </div>This page is still being developed.
|}

=== What? ===
This article provides a basic guide to setting up a read-only-root-based Alpine Linux system with several boot environments and atomic upgrades using rEFInd and btrfs.
=== Why? ===
Read-only root and atomic upgrades with ability to easily rollback or boot previous configurations is a concept that got some popularity recently. Distributions providing and promoting such features, for example, are [https://silverblue.fedoraproject.org/ Fedora Silverblue], [https://microos.opensuse.org/ Opensuse MicroOS], [https://nixos.org NixOS] and [https://guix.gnu.org GNU Guix].

While Alpine Linux has it's killer features it lacks mentioned above ones on default setup. This is a proof of concept that it's possible to implement them in a minimal way on a minimal system.

{{Note|Alpine Linux can also boot from RAM in '''diskless mode''' (see [[Installation]]) which supports preserving changes between reboots using [[lbu]].}}

= Preparation =
You should have bootable Alpine media. The process to obtain it decribed on the [[Installation|installation page.]]
{{Warning|Since version available in Alpine repositories lacks btrfs driver you should download rEFInd on [https://www.rodsbooks.com/refind/getting.html the official website] and copy it to installation media}}

= Partitioning disks =
In this guide it is assumed that you have a fresh UEFI system without OS and just managed to boot into live Alpine using USB flash drive or CD.
The first step is creating partition table on your HDD/SSD target device (<code>/dev/sda</code> here):
<pre># apk add gptfdisk
# gdisk /dev/sda
> o ↵
> y ↵
> w ↵
> y ↵
</pre>
Now we can define the partitions:
<pre># cgdisk /dev/sda</pre>
Partition creation process consists of several steps:
# Start sector - you can safely use default value by pressing ↵
# Size
# Type (as hex code) - EFI is ef00, Linux filesystem is 8300, Swap is 8200.
Result table:
<pre>Part. # Size Partition Type Partition Name
----------------------------------------------------------------
1 200.0 MiB EFI System EFI
2 200.0 GiB Linux filesystem ROOT
3 32.0 GiB Linux swap SWAP</pre>
<code>ROOT</code> partition name will later be used in rEFInd configuration to identify boot volume.
Next step is creating filesystems:
<pre># mkfs.vfat -F32 /dev/sda1
# mkfs.btrfs /dev/sda2
# mkswap /dev/sda3</pre>
Now we can mount our root volume:
<pre># mount -t btrfs /dev/sda2 /mnt</pre>
= File system structure =
Now we should create file structure that would provide reliable atomic system upgrades. 
Start with following directories: 
<pre># mkdir /mnt/next</pre>
Stores next <code>current</code> link. 
<pre># mkdir /mnt/commons</pre>
Stores common non-snapshotting subvolumes, is necessary due to how busybox <code>mv</code> does atomic link replacement. 
We may populate it right away:
<pre># btrfs subvolume create /mnt/commons/@var@tmp
# btrfs subvolume create /mnt/commons/@var@cache
# btrfs subvolume create /mnt/commons/@var@log
# btrfs subvolume create /mnt/commons/@home</pre>
If you use flatpak, you may also want to keep it's directory separate:
<pre># btrfs subvolume create /mnt/commons/@var@lib@flatpak</pre>
Next, most important directories:
<pre># mkdir /mnt/snapshots</pre>
Stores directories containing snapshots belonging to one generation. 
<pre># mkdir /mnt/links</pre>
Stores generations of directories containing links to snapshot generations. 
Let's create first generation and populate it with one OS root snapshot <code>@</code>:
<pre># NEWSNAPSHOTS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/$NEWSNAPSHOTS"
# btrfs subvolume create /mnt/$NEWSNAPSHOTS/@</pre>
Populate <code>links</code>:
<pre># NEWLINKS="$(date -u +"%Y%m%d%H%M%S")$(cat /dev/urandom | tr -dc 'a-zA-Z' | fold -w 8 | head -n 1)"
# mkdir "/mnt/links/$NEWLINKS"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/0"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/1"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/2"
# ln -s "../../snapshots/$NEWSNAPSHOTS" "/mnt/links/$NEWLINKS/3"</pre>
You can have as many links as you like, just apply changes to rEFInd config and upgrade scripts described below accordingly. 
Link that will point to latest links generation:
<pre># ln -s "./links/$NEWLINKS" /mnt/current</pre>
This setup allows us to just have static rEFInd config that points to to <code>/current/0/@</code>, <code>/current/1/@</code>, etc. while the actual underlying boot environment will change with each upgrade. 
But how will fs mounting services know which snapshot generation is currently loaded? 
The answer is common <code>fstab</code> in the btrfs root. 
Get UUIDs of the partitions first:
<pre># blkid > /mnt/fstab</pre>
Now edit fstab accordingly:
<pre># vi /mnt/fstab</pre>
Example:
<pre>UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 / btrfs subvol=CURRENT_SNAPSHOTS_PATH/@,ro,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/tmp btrfs subvol=/commons/@var@tmp,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/cache btrfs subvol=/commons/@var@cache,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/log btrfs subvol=/commons/@var@log,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /var/lib/flatpak btrfs subvol=/commons/@var@lib@flatpak,rw,noatime 0 0
UUID=b9ff5e7b-e128-4e64-861a-2fdd794a9828 /home btrfs subvol=/commons/@home,rw,noatime 0 0
# UUID=2FE6-837A /boot/efi vfat rw,noatime,discard 0 2
tmpfs /tmp tmpfs mode=1777,noatime,nosuid,nodev,size=2G 0 0
UUID=f0239163-9d46-47c1-67a4-3ee1d63d0676 swap swap rw,noatime,discard 0 0</pre>
<code>CURRENT_SNAPSHOTS_PATH</code> will be replaced by scripts with, for example, <code>/snapshots/20210411212549sdBXyLxg</code>, and the result will be piped into <code>/etc/fstab</code> of a created <code>@</code> snapshot during new generation preparations. 
Root btrfs volume structure mounted on <code>/mnt</code>:
<pre>|--mnt
| |--commons
| | |--@var@tmp
| | |--@var@cache
| | |--@var@log
| | |--@var@lib@flatpak
| | |--@home
| |--current
| |--fstab
| |--links
| | |--20210411213742qwrXAJBz
| | | |--0
| | | |--1
| | | |--2
| | | |--3
| |--next
| |--snapshots
| | |--20210411212549sdBXyLxg
| | | |--@</pre>

= Base system install =
With the directory strtucture prepared we can start installation of a basic Alpine Linux system. 
Considering that installation is done from Alpine system, we only need following parts of [[Alpine_Linux_in_a_chroot|the process]]:
<pre># apk -X https://dl-cdn.alpinelinux.org/alpine/latest-stable/main -U --allow-untrusted -p /mnt/snapshots/20210411212549sdBXyLxg/@ --initdb add alpine-base</pre>
Now we can setup basic chroot to complete the installation process:
<pre># export SNP="/mnt/snapshots/20210411212549sdBXyLxg/@"

# mount -o bind /dev $SNP/dev
# mount -t proc none $SNP/proc
# mount -o bind /sys $SNP/sys

# mkdir -p $SNP/var/tmp
# mount -o bind /mnt/commons/@var@tmp $SNP/var/tmp

# mkdir -p $SNP/var/cache
# mount -o bind /mnt/commons/@var@cache $SNP/var/cache

# mkdir -p $SNP/var/log
# mount -o bind /mnt/commons/@var@log $SNP/var/log

# mkdir -p $SNP/var/lib/flatpak
# mount -o bind /mnt/commons/@var@lib@flatpak $SNP/var/lib/flatpak

# mkdir -p $SNP/home
# mount -o bind /mnt/commons/@home $SNP/home

# cp -L /etc/resolv.conf /mnt/etc/
# chroot /mnt /bin/sh</pre>

As soon as you in chroot, define repositories:
<pre># mkdir -p /etc/apk
# echo "https://dl-cdn.alpinelinux.org/alpine/latest-stable/main" > /etc/apk/repositories</pre>
Example shows only <code>main</code>, but you should also add <code>testing</code> and <code>community</code> if you need any packages in those. 
Now it's time for firmware, kernel and btrfs packages:
<pre># apk add -U linux-firmware linux-lts btrfs-progs</pre>
You may want to change <code>linux-firmware</code> to a custom set of firmware packages suitable for you system, for example <code>linux-firmware-amd linux-firmware-amd-ucode linux-firmware-amdgpu linux-firmware-ath10k linux-firmware-qca</code> for typical AMD laptop. 
It is also important to add <code>btrfs</code> feature to <code>mkinitfs.conf</code> and run <code>mkinitfs</code> manually:
<pre># vi /etc/mkinitfs/mkinitfs.conf
# mkinitfs</pre>
These steps prepare kernel and generate <code>initramfs</code> which later will be used to boot from our first snapshot. 
After that you should install any package you may need on first boot.

{{Warning|In case your PC only has wireless connection you should also install and configure any suitable networking software, like <code>iwd</code>, so you won't end up severed from network on your first boot.}}

{{Note|Due to root being immutable during operation, it's recommended to install package <code>openresolv</code> to support changing network connection. In this case <code>/etc/resolvconf.conf</code> should have <code>resolv_conf{{=}}/tmp/resolv.conf</code>, <code>/etc/resolv.conf</code> should be moved to <code>/tmp/resolv.conf</code> and a link to the new resolv.conf location should be created: <code>ln -sfn /tmp/resolv.conf /etc/resolv.conf</code>.
You may also use static DNS, but this would make your network activity directly identifiable to the DNS server provider, therefore it's not recommended.
}}

With the snapshot prepared we can chroot out of it and unmount everything:
<pre># exit
# umount $SNP/dev
# umount $SNP/proc
# umount $SNP/sys

# umount $SNP/var/tmp

# umount $SNP/var/cache

# umount $SNP/var/log

# umount $SNP/var/lib/flatpak

# umount $SNP/home</pre>

...and inject fstab:
<pre># sed "s#CURRENT_SNAPSHOTS_PATH#/snapshots/20210411212549sdBXyLxg#g" /mnt/fstab > "/mnt/snapshots/20210411212549sdBXyLxg/@/etc/fstab"</pre>

Finish editing snapshot by setting <code>ro</code> flag and unmounting root volume:
<pre># btrfs property set -ts "/mnt/snapshots/20210411212549sdBXyLxg/@" ro true
# umount /mnt</pre>

= Bootloader installation =
{{Note|The example demonstrated here only make use of rEFInd bootloader as it is relatively easy to install manually and generally easy to use. You may however setup any prefered bootloader given it supports btrfs and can be configured to boot specific snapshot.}}
Mount the EFI partition:
<pre># mount -t vfat /dev/sda1 /mnt
# mkdir /mnt/EFI</pre>
Unpack prepared rEFInd archive and copy relevant files to <code>/mnt/EFI/</code>
<pre># unzip refind-bin-version.zip
# cp -r refind-bin-version/refind /mnt/EFI/
# cd /mnt/EFI/refind</pre>
Delete all unnecessary files - everything that is not for your CPU architecture:
<pre># rm -r drivers_aa64 drivers_ia32 tools_aa64 tools_ia32 refind_aa64.efi refind_ia32.efi</pre>
Rename config file and edit it:
<pre># mv refind.conf-sample refind.conf
# vi refind.conf</pre>
And append following to the end of the file:
<pre>
menuentry "Alpine Linux" {
icon /EFI/refind/icons/os_linux.png
volume "ROOT"
loader /current/0/@/boot/vmlinuz-lts
initrd /current/0/@/boot/initramfs-lts
options "root=/dev/sda2 rootfstype=btrfs rootflags=subvol=/current/0/@ resume=/dev/sda3 ro,noatime quiet splash"

submenuentry "Boot fallback 1" {
loader /current/1/@/boot/vmlinuz-lts
initrd /current/1/@/boot/initramfs-lts
options "/dev/sda2 rootfstype=btrfs rootflags=subvol=/current/1/@ resume=/dev/sda3 ro,noatime quiet splash"
}

submenuentry "Boot fallback 2" {
loader /current/2/@/boot/vmlinuz-lts
initrd /current/2/@/boot/initramfs-lts
options "/dev/sda2 rootfstype=btrfs rootflags=subvol=/current/2/@ resume=/dev/sda3 ro,noatime quiet splash"
}

submenuentry "Boot fallback 3" {
loader /current/3/@/boot/vmlinuz-lts
initrd /current/3/@/boot/initramfs-lts
options "/dev/sda2 rootfstype=btrfs rootflags=subvol=/current/3/@ resume=/dev/sda3 ro,noatime quiet splash"
}
}</pre>
<code>/dev/sda2</code> and <code>/dev/sda3</code> are the nodes of <code>ROOT</code> and <code>SWAP</code> devices.

Immutable root with atomic upgrades

2021-06-05T12:31:02Z

Mvsn:

Immutable root with atomic upgrades

2021-06-05T11:31:43Z

Mvsn:

Talk:Immutable root with atomic upgrades

2021-05-31T23:04:42Z

Mvsn: Created page with "User:Sb1, regarding diskless mode note: thanks for reminding about it, but it's a different setup with its own features, so I reduced the note, but left the links. Similar..."

Immutable root with atomic upgrades

2021-05-31T22:52:24Z

Mvsn:

Immutable root with atomic upgrades

2021-05-22T14:02:31Z

Mvsn:

Immutable root with atomic upgrades

2021-05-22T12:30:19Z

Mvsn:

Immutable root with atomic upgrades

2021-05-22T12:27:17Z

Mvsn:

Immutable root with atomic upgrades

2021-05-22T11:49:11Z

Mvsn:

Immutable root with atomic upgrades

2021-05-22T11:06:11Z

Mvsn:

Immutable root with atomic upgrades

2021-05-22T11:05:44Z

Mvsn:

Immutable root with atomic upgrades

2021-05-22T09:26:44Z

Mvsn:

Immutable root with atomic upgrades

2021-05-22T08:25:15Z

Mvsn:

Immutable root with atomic upgrades

2021-05-03T14:06:00Z

Mvsn:

Immutable root with atomic upgrades

2021-05-02T21:14:00Z

Mvsn:

Immutable root with atomic upgrades

2021-05-02T16:49:27Z

Mvsn:

Immutable root with atomic upgrades

2021-04-24T14:46:29Z

Mvsn:

Immutable root with atomic upgrades

2021-04-20T14:13:25Z

Mvsn:

Immutable root with atomic upgrades

2021-04-19T09:27:27Z

Mvsn:

Help talk:Editing

2021-04-18T22:28:58Z

Mvsn: Permission issue got resolved

Immutable root with atomic upgrades

2021-04-18T22:27:40Z

Mvsn: Immutable root with atomic upgrades

Help talk:Editing

2021-04-18T22:26:59Z

Mvsn:

Is it possible to contribute to wiki? I wanted to write an article but I can't create any page. Any attempt to post first WIP part gets marked as harmful.