#3623 PR `merged`: Enhance Btrfs filesystem support Part 1¶

Labels: enhancement, fixed / solved / done

svlv opened issue at 2026-07-31 14:11:¶

Pull Request Details:¶

Type: Enhancement
Impact: Normal
Reference to related issue (URL):
How was this pull request tested?
SLES 16.0, openSUSE Leap 16.1 and SLES 12.5 were recovered successfully.

I created Btrfs filesystems with individual features enabled (for block-group-tree, the no-holes and free-space-tree features were also enabled as it's mandatory), with all features enabled and with all features disabled. In all cases, the filesystems were recovered with the expected feature set. For the mixed-bg feature, sectorsize and nodesize must be identical, and recovery preserved this requirement correctly.
Example:
mkfs.btrfs -f --sectorsize 4096 --nodesize 4096 -O mixed-bg,^quota,^extref,^raid56,^skinny-metadata,^no-holes,^free-space-tree,^raid1c34,^zoned,^block-group-tree,^squota /dev/sdb1
Description of the changes in this pull request:
Support recovery of enabled Btrfs filesystem features, nodesize, and sectorsize by backing up their actual values and implicitly passing them to mkfs.btrfs during recovery, preventing them from being overridden by default values.

The newly supported options are stored in disklayout.conf in the same way as blocksize, fragmentsize, etc. are stored for ext* filesystems.

The validation logic was added primarily to mitigate code injection risks and to ensure that the recovered values are valid.

Additionally, I wrote unit tests to simplify the development and validation process. If you would prefer not to include them, let me know and I will remove the test file. Tests can be run with: bats tests/bats/001_filesystems_functions.bats

I’m also preparing additional changes to further improve Btrfs support, but I’d first like to hear your feedback on changes in this PR as it may not be interesting enough.

Potentially fixes https://github.com/rear/rear/issues/3545

Pages that I've used during development:
https://btrfs.readthedocs.io/en/latest/mkfs.btrfs.html#man-mkfs-filesystem-features
https://btrfs.readthedocs.io/en/latest/btrfs-man5.html#filesystem-features

codacy-production commented at 2026-07-31 14:12:¶

Up to standards ✅¶

🟢 Issues 0 issues

>
> > **Results:** > `0` new issues > > [View in > Codacy](https://app.codacy.com/gh/rear/rear/pull-requests/3623/issues) >

_{NEW Get contextual insights on your PRs based on Codacy's
metrics, along with PR and Jira context, without leaving GitHub. Enable
AI
reviewer}
_{TIP This summary will be updated as you push new changes.}

jsmeix commented at 2026-08-03 10:00:¶

@svlv
thank you for this valuable enhancement!

jsmeix commented at 2026-08-03 10:44:¶

I tested "rear mkrescue" with this changes
and noticed that the syntax of the

fs ... btrfs ...

entry in disklayout.conf changed
in my case on SLES15 SP6 with its default btrfs structure
from before (long line shown wrapped here)

fs /dev/vda2 / btrfs
 uuid=bad9f5d9-6a37-4902-b5fc-ded16e84f357
 label=
 options=rw,relatime,discard=async,space_cache=v2,subvolid=267,subvol=/@/.snapshots/1/snapshot

to now with this changes here (long line shown wrapped here)

fs /dev/vda2 / btrfs
 uuid=bad9f5d9-6a37-4902-b5fc-ded16e84f357
 label=
 nodesize=16384
 sectorsize=4096
 features=extref,free-space-tree,no-holes,skinny-metadata
 options=rw,relatime,discard=async,space_cache=v2,subvolid=267,subvol=/@/.snapshots/1/snapshot

i.e. those new options got inserted

nodesize=16384 sectorsize=4096 features=extref,free-space-tree,no-holes,skinny-metadata

I hope the new inserted options do not cause issues
at whatever code places which might expect the
ordering of the options from before the changes here.

I think the new options nodesize sectorsize and features
should be documented in
https://github.com/rear/rear/blob/master/doc/user-guide/06-layout-configuration.md
there near the end in the section
"Disk layout file syntax"
at
"Filesystems"
for example like (long line shown wrapped here)

fs <device> <mountpoint> <filesystem type>
 [uuid=<uuid>]
 [label=<label>]
 [blocksize=<block size(B)>]
 [<reserved_blocks=<nr of reserved blocks>]
 [max_mounts=<nr>]
 [check_interval=<number of days>d]
 [nodesize=<btrfs node size>]
 [sectorsize=<btrfs sector size>]
 [features=<btrfs filesystem features>]
 [options=<filesystem options>]

which is currently online here:
https://github.com/rear/rear/blob/master/doc/user-guide/06-layout-configuration.md#filesystems

jsmeix commented at 2026-08-03 11:41:¶

The following is is a general issue.
It does not directly belong to this specific pull request.

Regarding the basic functionality description in
https://github.com/rear/rear/pull/3623#issue-5030361037

Support recovery of enabled Btrfs filesystem features,
nodesize, and sectorsize by backing up their actual values
and implicitly passing them to mkfs.btrfs during recovery,
preventing them from being overridden by default values.

There are generic problems with such functionality:

On the one hand ReaR intends to recreate a system
as much as possible as it was before.

On the other hand it is impossible to determine
how a system is actually meant to be.

What I mean is shown by this issue here:

On my SLES15 SP6 with its default btrfs structure
all mkfs command calls from the system installytion
that I can find are only mkfs.btrfs --force /dev/vda2
(/dev/vda2 is the system partition of my only disk)

# find /var/log/YaST2 -type f | xargs grep -o 'mkfs.*'

/var/log/YaST2/yast-installation-logs/YaST2/y2log:
 mkfs.btrfs --force '/dev/vda2'")
...

So my btrfs filesystem was created with mkfs.btrfs defaults
which is what the btrfs filesystem setup is meant to be.

To recreate the btrfs filesystem as it is meant to be
would be to call plain mkfs.btrfs --force /dev/vda2.

Also
https://github.com/rear/rear/issues/3545
is a good example how things fail when trying
to recreate a system as it was before
instead of recreating as it is meant to be
when "just use defaults" is meant to be.

But it is impossible to determine what is meant to be
because in practice it is impossible to determine
if a specific setting is there by user intent
or if it is there just by default.

So what ReaR tries to do are endless tons of efforts
to recreate a system as much as possible as it was before.

But regardless how much effort we put into that task,
there will be always some settings which are not (yet)
monitored by ReaR so some recreated systems will
get recreated different than it was before
AND
if "just use defaults" is meant then recreating
settings as they were before is not what is meant
and furthermore that can lead to weird issues like
https://github.com/rear/rear/issues/3545

I remember the endless efforts to recrate XFS filesystems.
E.g. see the reasoning for MKFS_XFS_OPTIONS in default.conf
https://github.com/rear/rear/blob/rear-2.9/usr/share/rear/conf/default.conf#L699
and for more info the related
https://github.com/rear/rear/issues/1998
and
https://github.com/rear/rear/pull/2005

I think btrfs is even more complex than XFS.

I think in practice only dd recreates as it was before.

svlv commented at 2026-08-03 12:29:¶

If we are considering a default system created by an OS installer with the default options, and btrfs-progs versions are the same on both the source system and the rescue system, then yes, there are no issues.

However, systems with filesystems that were created manually, with features implicitly enabled/disabled and other options changed, cannot be recovered by ReaR correctly. By “correctly,” I mean that the filesystem options will be changed during recovery.

The issue mentioned https://github.com/rear/rear/issues/3545 resulted in a non-bootable system in my case.

I am not proposing that ReaR should recover all filesystem options, since that would be quite a complex task. I am proposing some improvements to back up and restore Btrfs filesystem features, as well as nodesize and sectorsize, because they are important for mixed block groups.

If based on your experience you think that this is not worth the effort, then fair enough. I will finish the Btrfs improvements I'm currently working on (Part 2) and see how things go.

jsmeix commented at 2026-08-03 12:59:¶

@svlv

I think you misunderstood my recent comment
https://github.com/rear/rear/pull/3623#issuecomment-5165854035

I made this comment here as a generic comment which
"does not directly belong to this specific pull request".
This specific pull request is an appreciated enhancement,
cf. my above comment,
https://github.com/rear/rear/pull/3623#issuecomment-5164936333

thank you for this valuable enhancement!

I would not have written "valuable enhancement"
if I think "it is not worth the effort".

svlv commented at 2026-08-03 13:03:¶

@jsmeix

Hmm, yes, I likely misunderstood you

svlv commented at 2026-08-03 13:37:¶

please verify that the new inserted options
nodesize sectorsize and features
in fs ... btrfs ... entries in
var/lib/rear/layout/disklayout.conf
do not cause issues at whatever code places
which might expect the ordering of the options
from before the changes here.

I didn't find any places where these new options could break the logic

jsmeix commented at 2026-08-04 09:31:¶

@rear/contributors
please have a look and review it (as time permits).

jsmeix commented at 2026-08-05 08:29:¶

@rear/contributors
I would like to merge it today afternoon
unless there are objections.

[Export of Github issue for rear/rear.]

#3623 PR merged: Enhance Btrfs filesystem support Part 1¶