[PATCH 0/3] btrfs-progs: updates related to seed device and v6.17 kernel

[PATCH 0/3] btrfs-progs: updates related to seed device and v6.17 kernel

[Qu Wenruo]

Kernel commit 40426dd147ff ("btrfs: use the super_block as holder when
mounting file systems") changed the block device holder so that each
device of a mounted btrfs can only belong to a single fs.

This is fine for most users, but for a corner case of seed devices, it
can be problematic.

As previously we allow the same seed device to be mounted through both
the seed device and the sprouted fs, as at that time all btrfs devices
share the same holder.

But now since each block device can only belong to a single mounted fs,
it means the seed device can only be mounted through either the seed
device itself or a sprouted fs, not both at the same time.

This series will update the docs to be more explicit about the seed
device mounting behavior, and updated the test case misc/046 to follow
the new kernel behavior.

And since we're here, also update a note where newer kernel fix a bug in
orphan roots cleanup.


Qu Wenruo (3):
  btrfs-progs: docs/seed: update a note related to orphan roots cleanup
  btrfs-progs: docs/seed: add extra notes for v6.17 and newer kernels
  btrfs-progs: misc-tests: do not try to mount a block device into
    different filesystems

 Documentation/ch-seeding-device.rst           | 14 +++++++++++++-
 tests/misc-tests/046-seed-multi-mount/test.sh | 17 ++++++++---------
 2 files changed, 21 insertions(+), 10 deletions(-)

--
2.50.1

[PATCH 1/3] btrfs-progs: docs/seed: update a note related to orphan roots cleanup

[Qu Wenruo]

There is a note about a bug that mount a fs RO first, then remount it
RW, will make btrfs to skip the orphan roots cleanup.

However it's no longer the case after kernel commit 44c0ca211a4d
("btrfs: lift read-write mount setup from mount and remount"), as that
commit unify the pre-RW mount checks, and will always do the orphan
roots cleanup.

Just update the note so that it won't cause any confusion.

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 Documentation/ch-seeding-device.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/ch-seeding-device.rst b/Documentation/ch-seeding-device.rst
index e04dd28d9ff8..8ca55dacd6a5 100644
--- a/Documentation/ch-seeding-device.rst
+++ b/Documentation/ch-seeding-device.rst
@@ -26,11 +26,13 @@ filesystem at :file:`/path` ready for use.
 
 .. note::
 
-        There is a known bug with using remount to make the mount writeable:
+        There was a known bug with using remount to make the mount writeable:
         remount will leave the filesystem in a state where it is unable to
         clean deleted snapshots, so it will leak space until it is unmounted
         and mounted properly.
 
+	That bug is fixed in v5.11 and newer kernels.
+
 Furthermore, deleting the seeding device from the filesystem can turn it into
 a normal filesystem, provided that the writable device can also contain all the
 data from the seeding device.
-- 
2.50.1

[PATCH 2/3] btrfs-progs: docs/seed: add extra notes for v6.17 and newer kernels

[Qu Wenruo]

[BEHAVIOR CHANGE]
In the incoming v6.17 kernel release, due to the changes in commit
40426dd147ff ("btrfs: use the super_block as holder when mounting file
systems"), we can no longer mount a seed device through both sprouted
fs and the seed device.

E.g.

 # mkfs.btrfs -f /dev/test/scratch1
 # mount /dev/test/scratch1 /mnt/btrfs
 # xfs_io -f -c "pwrite 0 16m" /mnt/btrfs/foobar
 # umount /mnt/btrfs
 # btrfstune -S1 /dev/test/scratch1
 # mount /dev/test/scratch1 /mnt/btrfs
 # btrfs device add /dev/test/scratch2 /mnt/btrfs

 Now the sprouted fs is mount, but if one wants to mount the seed
 device, it will fail:

 # mount /dev/test/scratch1  /mnt/btrfs/
 mount: /mnt/btrfs: /dev/mapper/test-scratch1 already mounted or mount point busy.
        dmesg(1) may have more information after failed mount system call.

 The only new dmesg is:

 BTRFS error: failed to open device for path /dev/mapper/test-scratch1 with flags 0x23: -16

[CAUSE]
After that kernel commit, each block device will have its own unique
holder (super block).

This super block block device holder is critical to pass device events
like freeze/thaw/missing to each filesystem.

And after the seed device is sprouted, the holder for the seed device is
the super block of the sprouted fs.

But if some one else tries to mount the seed device again, it will be a
new super block as the holder passed into bdev_file_open_by_path().

Since the seed device already has a different holder, this new
bdev_file_open_by_path() will fail with -EBUSY.

[ENHANCEMENT]
This is a kernel behavior change, but considering the benefit (proper
bdev events passing into the fs) I'd say the old behavior is more like a
hack or a coincidence, other than a properly designed behavior.

So update the documentation to make it more explicit.

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 Documentation/ch-seeding-device.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/ch-seeding-device.rst b/Documentation/ch-seeding-device.rst
index 8ca55dacd6a5..7ff35c3a3f8d 100644
--- a/Documentation/ch-seeding-device.rst
+++ b/Documentation/ch-seeding-device.rst
@@ -19,6 +19,16 @@ read-only, it can be used to seed multiple filesystems from one device at the
 same time. The UUID that is normally attached to a device is automatically
 changed to a random UUID on each mount.
 
+.. note::
+
+	Before v6.17 kernel, a seed device can be mounted independently along
+	with sprouted filesystems.
+	But since v6.17 kernel, a seed device can only be mounted either through
+	a sprouted filesystem, or the seed device itself, not both at the same time.
+
+	This is to ensure a block device to have only a single filesystem bounded
+	to it, so that runtime device missing events can be properly handled.
+
 Once the seeding device is mounted, it needs the writable device. After adding
 it, unmounting and mounting with :command:`umount /path; mount /dev/writable
 /path` or remounting read-write with :command:`remount -o remount,rw` makes the
-- 
2.50.1

[PATCH 3/3] btrfs-progs: misc-tests: do not try to mount a block device into different filesystems

[Qu Wenruo]

Since kernel commit 40426dd147ff ("btrfs: use the super_block as holder
when mounting file systems"), the kernel will not allow a block device
belonging to two different filesystems.

This means a seed device can only be mounted through either the sprouted
fs, or the seed device, not both at the same time.

Although a seed device can still be shared between different sprouted
fs, only one of those fs can be mounted.

Considering the extra benefit (extra protection, better device events
handling), it's worthy to do the kernel behavior change.

Update the test case to follow the new limits.

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 tests/misc-tests/046-seed-multi-mount/test.sh | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/tests/misc-tests/046-seed-multi-mount/test.sh b/tests/misc-tests/046-seed-multi-mount/test.sh
index 1ac80704f130..8c87e5b9ec09 100755
--- a/tests/misc-tests/046-seed-multi-mount/test.sh
+++ b/tests/misc-tests/046-seed-multi-mount/test.sh
@@ -1,5 +1,5 @@
 #!/bin/bash
-# Verify that a seeding device can be mounted several times
+# Verify that a seeding device can be shared by different sprout filesystems.
 
 source "$TEST_TOP/common" || exit
 
@@ -74,21 +74,20 @@ nextdevice() {
 	if [ "$md5sum" != "$md5sum2" ]; then
 		_fail "file contents not same after remount"
 	fi
+	# Unmount the new device so that the seed device won't be mounted
+	# when the sprout fs is already mounted.
+	# This is to compensate for the new v6.17 kernel, as each different
+	# fs will have different holder for a block device, and a single block
+	# device can not belong to different mounted filesystems.
+	run_check_umount_test_dev
 }
 
-# Keep previous device(s) mounted, create a new filesystem from the seeding device
+# Create a new filesystem from the seeding device, with previous devices unmounted.
 nextdevice 2
 nextdevice 3
 nextdevice 4
 nextdevice 5
 
-# Final umount
-# Skip seeding device, loop device 1,
-run_check $SUDO_HELPER umount ${loopdevs[2]}
-run_check $SUDO_HELPER umount ${loopdevs[3]}
-run_check $SUDO_HELPER umount ${loopdevs[4]}
-run_check $SUDO_HELPER umount ${loopdevs[5]}
-
 cleanup_loopdevs
 
 rm -rf -- mnt[0-9]
-- 
2.50.1

Re: [PATCH 0/3] btrfs-progs: updates related to seed device and v6.17 kernel

[Boris Burkov]

On Mon, Aug 04, 2025 at 09:22:35AM +0930, Qu Wenruo wrote:
> Kernel commit 40426dd147ff ("btrfs: use the super_block as holder when
> mounting file systems") changed the block device holder so that each
> device of a mounted btrfs can only belong to a single fs.
> 
> This is fine for most users, but for a corner case of seed devices, it
> can be problematic.
> 
> As previously we allow the same seed device to be mounted through both
> the seed device and the sprouted fs, as at that time all btrfs devices
> share the same holder.
> 
> But now since each block device can only belong to a single mounted fs,
> it means the seed device can only be mounted through either the seed
> device itself or a sprouted fs, not both at the same time.
> 
> This series will update the docs to be more explicit about the seed
> device mounting behavior, and updated the test case misc/046 to follow
> the new kernel behavior.
> 
> And since we're here, also update a note where newer kernel fix a bug in
> orphan roots cleanup.

Looks good to me, thanks.
Reviewed-by: Boris Burkov <boris@bur.io>

> 
> 
> Qu Wenruo (3):
>   btrfs-progs: docs/seed: update a note related to orphan roots cleanup
>   btrfs-progs: docs/seed: add extra notes for v6.17 and newer kernels
>   btrfs-progs: misc-tests: do not try to mount a block device into
>     different filesystems
> 
>  Documentation/ch-seeding-device.rst           | 14 +++++++++++++-
>  tests/misc-tests/046-seed-multi-mount/test.sh | 17 ++++++++---------
>  2 files changed, 21 insertions(+), 10 deletions(-)
> 
> --
> 2.50.1
>