[PATCH] btrfs-progs: docs: add seeding device section for btrfs-man5

[PATCH] btrfs-progs: docs: add seeding device section for btrfs-man5

[Sidong Yang]

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

Signed-off-by: Sidong Yang <realwakka@gmail.com>
---
 Documentation/btrfs-man5.asciidoc | 74 +++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)

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),
-- 
2.25.1

Re: [PATCH] btrfs-progs: docs: add seeding device section for btrfs-man5

[David Sterba]

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.

Re: [PATCH] btrfs-progs: docs: add seeding device section for btrfs-man5

[Sidong Yang]

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