diff options
authorDavid Sterba <>2015-06-02 19:34:40 +0200
committerDavid Sterba <>2015-06-03 12:52:56 +0200
commit0721c08dffdbbd959186ed3627c4b4728266e4fc (patch)
parent6a4a3acbc21d08065d64d57b08bb0d7f78e388ca (diff)
btrfs-progs: doc: update btrfstune manpage
Signed-off-by: David Sterba <>
1 files changed, 34 insertions, 22 deletions
diff --git a/Documentation/btrfstune.asciidoc b/Documentation/btrfstune.asciidoc
index 59f1500d..db9a97b9 100644
--- a/Documentation/btrfstune.asciidoc
+++ b/Documentation/btrfstune.asciidoc
@@ -3,7 +3,7 @@ btrfstune(8)
-btrfstune - tune various btrfs filesystem parameters
+btrfstune - tune various filesystem parameters
@@ -11,49 +11,61 @@ SYNOPSIS
-*btrfstune* is used to tune various btrfs filesystem parameters,you can
-enable/disable some extended features for btrfs.
+*btrfstune* can be used to enable, disable or set various filesystem
+parameters. The filesystem must be unmounted.
+The common usecase is to enable features that were not enabled at mkfs time.
+Please make sure that you have kernel support for the features. You can find a
+complete list of features and kernel version of their introduction at
+ .
--S <value>::
-Updates the seeding value.
-A positive value will enable seeding, zero will disable seeding, negtive is not allowed.
-Enable seeding forces a fs readonly so that you can use it to build other filesystems.
+-S <0|1>::
+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.
-Enable extended inode refs.
+Enable extended inode refs (hardlink limit per file in a directory is 65536). Since kernel 3.7.
-Enable skinny metadata extent refs.
+Enable skinny metadata extent refs (more efficient representation of extents). Since kernel 3.10.
-Enable no-holes feature. More efficient representation of file holes.
+Enable no-holes feature (more efficient representation of file holes). Since kernel 3.14.
Allow dangerous changes, e.g. clear the seeding flag or change fsid. Make sure
that you are aware of the dangers.
-Change fsid to a random generated UUID or continue previous change operation in
-case it was interrupted with the original UUID.
+Change fsid to a randomly generated UUID or continue previous fsid change
+operation in case it was interrupted.
-U <UUID>::
Change fsid to <UUID>.
The <UUID> should be a 36 bytes string in `printf`(3) format
-If there is a previous unfinished fsid change, it will only continue if the
-<UUID> matches the unfinished one.
+If there is a previous unfinished fsid change, it will continue only if the
+<UUID> matches the unfinished one or if you use the option '-u'.
WARNING: Cancelling or interrupting a UUID change operation will make the
filesystem temporarily unmountable. To fix it, rerun 'btrfstune -u' to restore
-the UUID and wait it complete.
+the UUID and let it complete.
-When mounting the new device, btrfs will check whether the seeding flag is set
-when try to open seeding device. If the user clears the seeding flag of the
-seeding device, the new device will not be mountable. Even setting the seeding
-flag back will not fix this problem, because the generation will be changed at
-that time. Clear the seeding flag may damage the new filesystem.
+WARNING: Clearing the seeding flag on a device may be dangerous.
+If a previously-seeding device is changed, all filesystems that used that
+device will become unmountable. Setting the seeding flag back will not fix
+that. +
+A valid usecase is "seeding device as a base image". Clear the seeding
+flag, update the filesystem and make it seeding again, provided that it's ok
+to throw away all filesystems built on top of the previous base.
-*btrfstune* will return 0 if no error happened.
-If any problems happened, 1 will be returned.
+*btrfstune* returns 0 if no error happened, 1 otherwise.
+This tool exists for historical reasons but is still in use today. The
+functionality is about to be merged to the main tool someday and *btrfstune*
+will become deprecated and removed afterwards.