btrfs-progs: docs: add section about seeding device
Issue: #341 Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
David Sterba
parent
1304eb9e12
commit
fc6818a46c
|
|
@ -19,6 +19,7 @@ tools. Currently covers:
|
|||
. file attributes
|
||||
. control device
|
||||
. filesystems with multiple block group profiles
|
||||
. seeding device
|
||||
|
||||
|
||||
MOUNT OPTIONS
|
||||
|
|
@ -1007,6 +1008,87 @@ that report space usage: 'filesystem df', 'device usage'. The command
|
|||
---------------
|
||||
|
||||
|
||||
SEEDING DEVICE
|
||||
--------------
|
||||
|
||||
The COW mechanism and multiple devices under one hood enable an interesting
|
||||
concept, called a seeding device: extending a read-only filesystem on a single
|
||||
device filesystem with another device that captures all writes. For example
|
||||
imagine an immutable golden image of an operating system enhanced with another
|
||||
device that allows to use the data from the golden image and normal operation.
|
||||
This idea originated on CD-ROMs with base OS and allowing to use them for live
|
||||
systems, but this became obsolete. There are technologies providing similar
|
||||
functionality, like 'unionmount', 'overlayfs' or 'qcow2' image snapshot.
|
||||
|
||||
The seeding device starts as a normal filesystem, once the contents is ready,
|
||||
*btrfstune -S 1* is used to flag it as a seeding device. Mounting such device
|
||||
will not allow any writes, except adding a new device by *btrfs device add*.
|
||||
Then the filesystem can be remounted as read-write.
|
||||
|
||||
Given that the filesystem on the seeding device is always recognized as
|
||||
read-only, it can be used to seed multiple filesystems, at the same time. The
|
||||
UUID that is normally attached to a device is automatically changed to a random
|
||||
UUID on each mount.
|
||||
|
||||
Once the seeding device is mounted, it needs the writable device. After adding
|
||||
it, something like 'remount -o remount,rw /path' makes the filesystem at
|
||||
'/path' ready for use. The simplest usecase is to throw away all changes by
|
||||
unmounting the filesystem when convenient.
|
||||
|
||||
Alternatively, 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.
|
||||
|
||||
The seeding device flag can be cleared again by *btrfstune -f -s 0*, eg.
|
||||
allowing to update with newer data but please note that this will invalidate
|
||||
all existing filesystems that use this particular seeding device. This works
|
||||
for some usecases, not for others, and a forcing flag to the command is
|
||||
mandatory to avoid accidental mistakes.
|
||||
|
||||
Example how to create and use one seeding device:
|
||||
|
||||
---------------
|
||||
# mkfs.btrfs /dev/sda
|
||||
# mount /dev/sda /mnt/mnt1
|
||||
# ... fill mnt1 with data
|
||||
# umount /mnt/mnt1
|
||||
# btrfstune -S 1 /dev/sda
|
||||
# mount /dev/sda /mnt/mnt1
|
||||
# btrfs device add /dev/sdb /mnt
|
||||
# mount -o remount,rw /mnt/mnt1
|
||||
# ... /mnt/mnt1 is now writable
|
||||
---------------
|
||||
|
||||
Now '/mnt/mnt1' can be used normally. The device '/dev/sda' can be mounted
|
||||
again with a another writable device:
|
||||
|
||||
---------------
|
||||
# mount /dev/sda /mnt/mnt2
|
||||
# btrfs device add /dev/sdc /mnt/mnt2
|
||||
# mount -o remount,rw /mnt/mnt2
|
||||
# ... /mnt/mnt2 is now writable
|
||||
---------------
|
||||
|
||||
The writable device ('/dev/sdb') can be decoupled from the seeding device and
|
||||
used independently:
|
||||
|
||||
---------------
|
||||
# btrfs device delete /dev/sda /mnt/mnt1
|
||||
---------------
|
||||
|
||||
As the contents originated in the seeding device, it's possible to turn
|
||||
'/dev/sdb' to a seeding device again and repeat the whole process.
|
||||
|
||||
A few things to note:
|
||||
|
||||
* it's recommended to use only single device for the seeding device, it works
|
||||
for multiple devices but the 'single' profile must be used in order to make
|
||||
the seeding device deletion work
|
||||
* block group profiles 'single' and 'dup' support the usecases above
|
||||
* the label is copied from the seeding device and can be changed by *btrfs filesystem label*
|
||||
* each new mount of the seeding device gets a new random UUID
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
`acl`(5),
|
||||
|
|
|
|||
|
|
@ -65,6 +65,7 @@ enabled by mkfs feature 'extref'.
|
|||
Enable seeding on a given device. Value 1 will enable seeding, 0 will disable it. +
|
||||
A seeding filesystem is forced to be mounted read-only. A new device can be added
|
||||
to the filesystem and will capture all writes keeping the seeding device intact.
|
||||
See also section 'SEEDING DEVICE' in `btrfs`(5).
|
||||
+
|
||||
WARNING: Clearing the seeding flag on a device may be dangerous.
|
||||
If a previously-seeding device is changed, all filesystems that used that
|
||||
|
|
|
|||
Loading…
Reference in a new issue