[PATCH] btrfs-progs: docs: discourage root btrfs usage without an initramfs

[PATCH] btrfs-progs: docs: discourage root btrfs usage without an initramfs

[Qu Wenruo]

For multi-device btrfs, device scanning is required before mounting, and
without an initramfs it's impossible to mount a multi-device btrfs.

Even if the rootfs is a single-device btrfs, there is nothing preventing
the end user to add a device to that btrfs, and fail the next boot.

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 Documentation/mkfs.btrfs.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/mkfs.btrfs.rst b/Documentation/mkfs.btrfs.rst
index 0d3d6051b0e7..0bc7b7ac3808 100644
--- a/Documentation/mkfs.btrfs.rst
+++ b/Documentation/mkfs.btrfs.rst
@@ -346,6 +346,10 @@ devices to scan at the time of mount.
         before all block devices are discovered. The waiting is usually done on the
         initramfs/initrd systems.
 
+        Thus using btrfs as a rootfs without an initramfs is not recommended.
+        Adding a new device to the rootfs can easily cause the next boot to fail, as
+        there is no way to register all devices prior to mounting.
+
 .. warning::
         RAID5/6 has known problems and should not be used in production.
 
-- 
2.55.0

Re: [PATCH] btrfs-progs: docs: discourage root btrfs usage without an initramfs

[David Sterba]

On Sat, Sep 12, 2026 at 06:55:32PM +0930, Qu Wenruo wrote:
> For multi-device btrfs, device scanning is required before mounting, and
> without an initramfs it's impossible to mount a multi-device btrfs.
> 
> Even if the rootfs is a single-device btrfs, there is nothing preventing
> the end user to add a device to that btrfs, and fail the next boot.
> 
> Signed-off-by: Qu Wenruo <wqu@suse.com>
> ---
>  Documentation/mkfs.btrfs.rst | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/Documentation/mkfs.btrfs.rst b/Documentation/mkfs.btrfs.rst
> index 0d3d6051b0e7..0bc7b7ac3808 100644
> --- a/Documentation/mkfs.btrfs.rst
> +++ b/Documentation/mkfs.btrfs.rst
> @@ -346,6 +346,10 @@ devices to scan at the time of mount.
>          before all block devices are discovered. The waiting is usually done on the
>          initramfs/initrd systems.
>  
> +        Thus using btrfs as a rootfs without an initramfs is not recommended.
> +        Adding a new device to the rootfs can easily cause the next boot to fail, as
> +        there is no way to register all devices prior to mounting.

That's not a good placement, we should write a full section how to use
btrfs without initrd and what are the caveats. A paragraph burried in
mkfs will probably never got noticed.

> +
>  .. warning::
>          RAID5/6 has known problems and should not be used in production.
>  
> -- 
> 2.55.0
> 

Re: [PATCH] btrfs-progs: docs: discourage root btrfs usage without an initramfs

[Qu Wenruo]

在 2026/9/15 02:48, David Sterba 写道:
> On Sat, Sep 12, 2026 at 06:55:32PM +0930, Qu Wenruo wrote:
>> For multi-device btrfs, device scanning is required before mounting, and
>> without an initramfs it's impossible to mount a multi-device btrfs.
>>
>> Even if the rootfs is a single-device btrfs, there is nothing preventing
>> the end user to add a device to that btrfs, and fail the next boot.
>>
>> Signed-off-by: Qu Wenruo <wqu@suse.com>
>> ---
>>   Documentation/mkfs.btrfs.rst | 4 ++++
>>   1 file changed, 4 insertions(+)
>>
>> diff --git a/Documentation/mkfs.btrfs.rst b/Documentation/mkfs.btrfs.rst
>> index 0d3d6051b0e7..0bc7b7ac3808 100644
>> --- a/Documentation/mkfs.btrfs.rst
>> +++ b/Documentation/mkfs.btrfs.rst
>> @@ -346,6 +346,10 @@ devices to scan at the time of mount.
>>           before all block devices are discovered. The waiting is usually done on the
>>           initramfs/initrd systems.
>>   
>> +        Thus using btrfs as a rootfs without an initramfs is not recommended.
>> +        Adding a new device to the rootfs can easily cause the next boot to fail, as
>> +        there is no way to register all devices prior to mounting.
> 
> That's not a good placement, we should write a full section how to use
> btrfs without initrd and what are the caveats. A paragraph burried in
> mkfs will probably never got noticed.

I'll add a dedicated chapter for device scan related behavior in man 5 
btrfs.

> 
>> +
>>   .. warning::
>>           RAID5/6 has known problems and should not be used in production.
>>   
>> -- 
>> 2.55.0
>>
>