[vgivanovic]

Examples, examples, examples!

Just today I failed to find an example of mounting multiple drives as one Btrfs filesystem. Plenty of how to create Btrfs filesystem examples. But how to mount them? Crickets. I eventually figured it out, but at a large cost in time.

[wtallis]

I think you just wasted a lot of time looking for complexity that you wrongly expected to exist. When I google "btrfs mount multiple device", two of the top three results include exactly the example you needed to see (and probably skipped over believing it couldn't be that simple), and the other one indirectly explains what's going on by discussing the necessity of a btrfs scan when using multiple devices (and how to construct an fstab entry if your boot process doesn't do a btrfs scan).

For the record: to mount a multiple device btrfs filesystem, use an ordinary mount command with any one of the block devices that are part of the file system. Every device contains information about what other devices are supposed to be part of that filesystem.

I'm not sure if there are any techniques documentation writers can use to avoid this "hiding in plain sight" kind of problem.

[planede]

> For the record: to mount a multiple device btrfs filesystem, use an ordinary mount command with any one of the block devices that are part of the file system. Every device contains information about what other devices are supposed to be part of that filesystem.

If something works "automagically" like this then I jump into thinking about failure modes. Will it mount if one of the other devices are missing or failing? Will it just warn that the raid is degraded and I should add a new device? Will it mount read-only?

> I'm not sure if there are any techniques documentation writers can use to avoid this "hiding in plain sight" kind of problem.

The problem is probably lack of emphasis. It's guess it's hard to achieve in writing, if a solution is simple than you don't need many words to explain it, then it becomes easy to skip over.

[wtallis]

> If something works "automagically" like this then I jump into thinking about failure modes. Will it mount if one of the other devices are missing or failing? Will it just warn that the raid is degraded and I should add a new device? Will it mount read-only?

That's all well-documented, but it can also be summarized by saying that btrfs does the right thing. It won't mount normally if it's missing any devices, because running in degraded mode shouldn't be a silent error (especially at mount time).