From postmarketOS Wiki


BTRFS is available on PostmarketOS for devices running close-to mainline kernels.

BTRFS offers Copy-on-Write which lowers the risk of data loss due to sudden power outage, compression which makes optimal use of the limited disk space available on many devices, snapshots, and other features.

PostmarketOS makes use of its snapshot feature via apk-snap and snapper, as well as the ability to choose the default subvolume to mount as / in a filesystem via [link to recovery script here].

When encountering a breaking bug in pmOS caused by installing, removing or upgrading software, this lets users switch from their currently mounted / to a snapshot taken directly before the breaking change was introduced. In effect, undoing the breaking change without affecting anything else on their system.

This increases margin of safety; both for people using PostmarketOS as a daily driver, and developers. Devs can set up their perfect on-device dev / test environment; hack freely, introduce breaking bugs, then roll back to their pristine environment again. All while keeping logs of what broke.

For users, the ability to roll back the system without losing your personal data on /home or apps, gives peace of mind.

How to install

To format your device using BTRFS, use pmbootstrap install --filesystem btrfs

To get automatic snapshots before and after apk {add,del,upgrade}, install apk-snap using $sudo apk add apk-snap.

Subvolume layout

BTRFS subvolumes in PostmarketOS follow @* naming scheme.

The toplevel subvolume, the BTRFS "filesystem" so to speak, is normally unmounted and is only mounted when creating read-write snapshots of read-only snapshots that can be booted into.

Default subvolumes:

@: the default root subvolume. This contains everything that doesn't belong to a different subvolume.

@home: where users home directories live. Having a @home subvol enables easy backup/restore solutions, separate from the root subvolume.

@root: root home directory which shouldn't be rolled back.

@var: contains logs, VMs, containers, flatpaks; and shouldn't roll back or have Copy-on-Write.

@tmp: snapshotting temporary files in /tmp is unnecessary, and would only eat storage space.

@snapshots: Having a separate subvolume for snapshots lets us switch out the @ subvol with a read-write snapshot without affecting snapshots.

@srv: contains data for Web and FTP servers, which shouldn't roll back.

How to use recovery script

When you want to undo a breaking change, do [recovery-script here]. You'll be presented with a list of snapshots and some useful metadata. Input the number of the snapshot you would like to switch to, and reboot.