1 files changed, 75 insertions, 0 deletions
diff --git a/Documentation/btrfstune.asciidoc b/Documentation/btrfstune.asciidoc
new file mode 100644
index 00000000..68fec4c9
--- /dev/null
+++ b/Documentation/btrfstune.asciidoc
@@ -0,0 +1,75 @@
+btrfstune(8)
+============
+
+NAME
+----
+btrfstune - tune various filesystem parameters
+
+SYNOPSIS
+--------
+*btrfstune* [options] <dev> [<dev>...]
+
+DESCRIPTION
+-----------
+*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 <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 (hardlink limit per file in a directory is 65536),
+enabled by mkfs feature 'extref'. Since kernel 3.7.
+-x::
+Enable skinny metadata extent refs (more efficient representation of extents),
+enabled by mkfs feature 'skinny-metadata'. Since kernel 3.10.
+-n::
+Enable no-holes feature (more efficient representation of file holes), enabled
+by mkfs feature 'no-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 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 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 let it complete.
+
+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* 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
+--------
+`mkfs.btrfs`(8)