Generate rEFInd manual boot stanzas from Btrfs snapshots
Generate rEFInd manual boot stanzas from Btrfs snapshots
This tool is used to automate a few tedious tasks required to boot into Btrfs snapshots from rEFInd. It is to rEFInd what grub-btrfs is to GRUB.
What it does is the following:
In case a separate /boot partition is detected only the fields relevant to / are modified ("subvol" and/or "subvolid") while the "loader" and "initrd" fields (the former may also be nested within the "options" field) remain unaffected.
It goes without saying that the consequence of having this kind of a setup is being unable to mitigate a problematic kernel upgrade by simply booting into a snapshot.
This tool will also detect a situation where / is mounted as a snapshot (which means that you've already booted into one), issue a warning and simply exit whereas, for instance, Snapper will happily continue creating its snapshots, regardless. This behavior is configurable and enabled by default.
The following conditions (some are probably superfluous at this point) must be satisfied in order for this tool to function correctly:
This tool is currently available only in the AUR which means that Arch Linux users (as well as users of derivative distributions, I imagine) can easily install it.
It comes with a script (refind-btrfs) which can be used to perform the described steps, on-demand (root privileges are required to run it). There is also a systemd service aptly named refind-btrfs.service which runs the tool in a background mode of operation where the described steps are performed automatically once a change (snapshot creation or deletion) happens in the watched snapshot directories which are the same ones as those in which it searches for snapshots. If you are using Snapper along with its capability to take regular snapshots on boot this service should take these into account as well because it is set to start before Snapper's relevant service does so (the one named snapper-boot.service).
Before running the script for the first time or enabling and starting the service make sure to at least check and perhaps modify the config file (/etc/refind-btrfs.conf) to suit your own needs.
If you wish to check the current status and log output of the running service you can do so by executing:
systemctl status refind-btrfs
journalctl -u refind-btrfs -bAlternatively, there exists a PyPI package but bear in mind that since libbtrfsutil isn't available on PyPI it needs to be already present in the system site packages (its Python bindings, to be precise) because it cannot be automatically pulled in as a dependency. Chances are that it is available for your distribution of choice (search for a package named "btrfs-progs") but you most probably already have it installed as I suppose you are using Btrfs, after all.
Also, every file contained in this directory should be copied to the following locations:
In case the custom generated boot stanza's icon feature (explained in the next section) is desired it can initially be enabled by installing this package with the following command:
pip install refind-btrfs[custom_icon]You should also create an empty directory named "refind-btrfs" in /var/lib as the tool expects that it is present. Additionally, if you wish to be able to use the Btrfs logo embedding mode of custom icon generation you should also copy the "icons" directory into the previously created one.
The configuration file can be found at /etc/refind-btrfs.conf, and each option is thoroughly explained in the sample config file.
In case you've opted to use the provided systemd service and wish to change the search directories (in this context, these are actually watched directories) in the config file while it is running you must restart it manually after doing so because the directory observer is started only once and an automatic restart is not performed.
The default configuration is meant to enable seamless integration with Snapper simply because I'm using it but the tool itself doesn't depend on it and ought to function with different setups. Also, by default the tool is configured for creating new writable snapshots intended for booting instead of in-place modification of the found snapshots' read-only flags as I believe this is the safer (or perhaps even saner) choice.
Timeshift users can try setting the default snapshot search directory to "/run/timeshift/backup/timeshift-btrfs/snapshots" and the corresponding maximum search depth to three.
If you're having trouble with the ESP being automatically located, the "esp_uuid" option could prove to be useful. If an actual UUID is provided (not the default, empty one), this value will be used to compare partition UUIDs (returned by lsblk) instead of comparing their types with hardcoded GPT UUID or MBR ID values.
Custom generated boot stanza icon support is also implemented, by default the source boot stanza's icon is reused. It is possible to provide one's own custom icon's path or to embed the Btrfs logo (comes in two variants and three sizes per each variant) into the source boot stanza's icon instead. This combined icon is then used as the generated boot stanza's icon.
In order for these two additional modes of operation (not the default one) to work an optional dependency has to be installed - namely, the Pillow library which can be installed from the official Arch Linux repository or from PyPI.
It is imperative that you don't just blindly try to boot into a given snapshot (simply because no errors were reported) before verifying the generated manual boot stanza, either by inspecting the file contents in which it was saved or by viewing the boot loader options using rEFInd and also not before verifying the chosen snapshot's fstab file.
Given a setup such as this one:
UUID=95250e8a-5870-45df-a7b3-3b3ee8873c16 / btrfs rw,noatime,compress-force=zstd:2,ssd,space_cache=v2,commit=15,subvolid=256,subvol=/@ 0 0menuentry "Arch Linux - Stable" {
icon /EFI/refind/icons/os_arch.png
volume ARCH
loader /@/boot/vmlinuz-linux
initrd /@/boot/initramfs-linux.img
options "root=PARTUUID=048d6fcd-c88c-504d-bd51-dfc0a5bf762d rw add_efi_memmap rootflags=subvol=@ initrd=@\boot\intel-ucode.img"
submenuentry "Boot - fallback" {
initrd /@/boot/initramfs-linux-fallback.img
}
submenuentry "Boot - terminal" {
add_options "systemd.unit=multi-user.target"
}
}five read-only snapshots located in the /.snapshots directory where this directory is itself mounted as a subvolume named @snapper-root (this last bit isn't particularly relevant):
| Absolute Path | Time of Creation | Subvolume ID |
|---|---|---|
| /.snapshots/1/snapshot | 10-12-2020 01:00:00 | 498 |
| /.snapshots/2/snapshot | 11-12-2020 02:00:00 | 499 |
| /.snapshots/3/snapshot | 12-12-2020 03:00:00 | 500 |
| /.snapshots/4/snapshot | 13-12-2020 04:00:00 | 501 |
| /.snapshots/5/snapshot | 14-12-2020 05:00:00 | 502 |
refind-btrfs.conf file changed such that the "selection_count" option is set to 3 instead of the default 5
When run, this tool should select the latest three snapshots (3, 4 and 5 from the list) and create new, writable ones from these in the directory configured by the "destination_dir" option where each snapsho
No open issues yet, or sync has not completed.