百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
R

refind-btrfs

> 编程语言
开源

从 Btrfs 快照生成 rEFInd 手动启动段

198 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

从 Btrfs 快照生成 rEFInd 手动启动段

refind-btrfs

Table of Contents

  • Description
  • Prerequisites
  • Installation
  • Configuration
  • Example
  • Implementation
  • Further Efforts

Description

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:

  • Gathers information about block devices present in the system
  • Identifies the ESP (either by GPT GUID or MBR ID)
  • Gathers information about mounted filesystems (from mtab) which are present on all of the found block devices
  • Identifies the root mount point and gathers information about the subvolume which is mounted at said mount point
  • Searches for snapshots of the identified subvolume in the configured directory (or directories)
  • Searches for rEFInd's main config file on the ESP and parses it to extract manual boot stanzas from it (included configs are also analyzed, if present)
  • Selects the configured number of latest snapshots and uses them as such if they are writable and if any aren't, it either (depending on the configuration):
    • sets their read-only flag to false, thus making them writable
    • creates new writable snapshots from them in the configured location
  • Aligns the root mount point in the fstab file of each selected snapshot with the snapshot itself
  • Deletes outdated previously created writable snapshots (if any exist)
  • Generates new manual boot stanzas from identified ones where every relevant field is aligned with each selected snapshot
  • Finally, it saves the generated manual boot stanzas in separate config files (outputs them to a subdirectory) and includes each file in the main config file so as not to needlessly clutter it

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.

Prerequisites

The following conditions (some are probably superfluous at this point) must be satisfied in order for this tool to function correctly:

  • mounted ESP (no automatic discovery and/or mounting is supported)
  • Btrfs formatted filesystem with a subvolume mounted as /
  • at least one snapshot of the root subvolume
  • rEFInd installation present on the ESP
  • at least one manual boot stanza (found in rEFInd's main config file or in any of the additional config files included within it) defined such that (see the ArchWiki for an example) its own "options" field or any such field belonging to at least one of its sub-menus contains definitions of the following boot loader options:
    • the "root" option must be matched with the root partition (by PARTUUID or PARTLABEL), its filesystem (by UUID or LABEL) or with a block device (by name) which itself represents the root partition
    • the "rootflags" option must define a "subvol" suboption which is matched with the root subvolume's logical path and/or a "subvolid" suboption which is matched with the root subvolume's ID

Installation

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 -b

Alternatively, 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:

  • refind-btrfs script to /usr/bin (or wherever it is you keep your system-wide executables)
  • refind-btrfs.conf-sample as refind-btrfs.conf (without the "-sample" suffix) to /etc
  • refind-btrfs.service to /usr/lib/systemd/system (if you are using systemd and wish to utilize the snapshot directory watching feature)

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:

bash
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.

Configuration

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.

Example

Given a setup such as this one:

  • device /dev/nvme0n1 where:
    • the ESP is on /dev/nvme0n1p3 mounted at /efi
    • / is on /dev/nvme0n1p8
    • /boot is included in /dev/nvme0n1p8 (not a separate partition)
  • the subvolume mounted as / is named @
  • fstab file's root mount point:
UUID=95250e8a-5870-45df-a7b3-3b3ee8873c16 / btrfs rw,noatime,compress-force=zstd:2,ssd,space_cache=v2,commit=15,subvolid=256,subvol=/@ 0 0
  • manual boot stanza defined in the refind.conf file (rEFInd's main config file, in this case):
menuentry "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

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Pythonbootbtrbkbtrfsrefind

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言