btrfs-progs: docs: add seeding device section for btrfs-man5

Commit Message

Sidong Yang Feb. 14, 2021, 5:17 p.m. UTC

This patch adds a section about seeding device for btrfs-man5.
Description and examples are from btrfs-wiki page.

Signed-off-by: Sidong Yang <[e-mail]>
---
 Documentation/btrfs-man5.asciidoc | 74 +++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)

Comments

David Sterba March 1, 2021, 8:57 p.m. UTC | #1

On Sun, Feb 14, 2021 at 05:17:38PM +0000, Sidong Yang wrote:
> This patch adds a section about seeding device for btrfs-man5.
> Description and examples are from btrfs-wiki page.

Sorry, but the contents of the wiki page are useless as documentation.
There's no explanation of the usecase just a bunch of commands.
Meanwhile I've written something that I consider good enough for
documenation, it's now in devel. Feel free to proofread it and enhance
with additional updates or examples if you think they're missing.

Sidong Yang March 4, 2021, 7:10 a.m. UTC | #2

On Mon, Mar 01, 2021 at 09:57:47PM +0100, David Sterba wrote:
> On Sun, Feb 14, 2021 at 05:17:38PM +0000, Sidong Yang wrote:
> > This patch adds a section about seeding device for btrfs-man5.
> > Description and examples are from btrfs-wiki page.
> 
> Sorry, but the contents of the wiki page are useless as documentation.
> There's no explanation of the usecase just a bunch of commands.
> Meanwhile I've written something that I consider good enough for
> documenation, it's now in devel. Feel free to proofread it and enhance
> with additional updates or examples if you think they're missing.

Okay, thanks for review.

Thanks,
Sidong

Patch

diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc
index e5edbe53..db2b5f1f 100644
--- a/Documentation/btrfs-man5.asciidoc
+++ b/Documentation/btrfs-man5.asciidoc
@@ -995,6 +995,80 @@  that report space usage: 'filesystem df', 'device usage'. The command
 ---------------
 
 
+SEEDING DEVICE
+--------------
+
+The original filesystem and devices are included as a readonly starting point to
+the new FS. All modifications go onto different devices and the COW machinery
+makes sure the original is unchanged.
+
+--------------------
+# dd if=/dev/zero of=/mnt/gentoo/btrfs-test-1 count=2 bs=1G
+# dd if=/dev/zero of=/mnt/gentoo/btrfs-test-2 count=2 bs=1G
+--------------------
+
+--------------------
+# losetup /dev/loop0 /mnt/gentoo/btrfs-test-1
+# losetup /dev/loop1 /mnt/gentoo/btrfs-test-2
+--------------------
+
+--------------------
+# mkfs.btrfs /dev/loop0
+--------------------
+
+--------------------
+# mount /dev/loop0 /mnt/test/
+# echo a > /mnt/test/a
+# echo b > /mnt/test/b
+--------------------
+
+--------------------
+# umount /mnt/test
+--------------------
+
+Now we will use this filesystem as a seed device:
+--------------------
+# btrfstune -S 1 /dev/loop0
+--------------------
+For more details, see `btrfstune`(8).
+
+--------------------
+# mount /dev/loop0 /mnt/test
+mount: block device /dev/loop0 is write-protected, mounting read-only
+# btrfs device add /dev/loop1 /mnt/test
+# ls /mnt/test
+a  b
+# echo c > /mnt/test/c
+bash: c: Read-only file system
+--------------------
+
+--------------------
+# mount -o remount,rw /mnt/test
+OR
+# umount /mnt/test
+# mount /dev/loop1 /mnt/test
+--------------------
+
+--------------------
+# echo c > /mnt/test/c
+# echo d > /mnt/test/d
+# umount /mnt/test
+--------------------
+
+--------------------
+# mount /dev/loop0 /mnt/test
+mount: block device /dev/loop0 is write-protected, mounting read-only
+# ls /mnt/test
+a  b
+# umount /mnt/test
+# mount /dev/loop1 /mnt/test
+# ls /mnt/test
+a  b  c  d
+# cat /mnt/test/c
+c
+--------------------
+
+
 SEE ALSO
 --------
 `acl`(5),