summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid Sterba <dsterba@suse.cz>2015-06-02 19:34:40 +0200
committerDavid Sterba <dsterba@suse.cz>2015-06-03 12:52:56 +0200
commit0721c08dffdbbd959186ed3627c4b4728266e4fc (patch)
tree459c745244485e33fbefb0a2082a797b347b4199
parent6a4a3acbc21d08065d64d57b08bb0d7f78e388ca (diff)
btrfs-progs: doc: update btrfstune manpage
Signed-off-by: David Sterba <dsterba@suse.cz>
-rw-r--r--Documentation/btrfstune.asciidoc56
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)
NAME
----
-btrfstune - tune various btrfs filesystem parameters
+btrfstune - tune various filesystem parameters
SYNOPSIS
--------
@@ -11,49 +11,61 @@ SYNOPSIS
DESCRIPTION
-----------
-*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
+https://btrfs.wiki.kernel.org/index.php/Changelog#By_feature .
OPTIONS
-------
--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.
-r::
-Enable extended inode refs.
+Enable extended inode refs (hardlink limit per file in a directory is 65536). Since kernel 3.7.
-x::
-Enable skinny metadata extent refs.
+Enable skinny metadata extent refs (more efficient representation of extents). Since kernel 3.10.
-n::
-Enable no-holes feature. More efficient representation of file holes.
+Enable no-holes feature (more efficient representation of file holes). Since kernel 3.14.
-f::
Allow dangerous changes, e.g. clear the seeding flag or change fsid. Make sure
that you are aware of the dangers.
-u::
-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
"%08x-%04x-%04x-%04x-%012x".
-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.
EXIT STATUS
-----------
-*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.
+
+COMPATIBILITY NOTE
+------------------
+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.
SEE ALSO
--------