Diffstat (limited to 'Documentation/btrfstune.asciidoc')
1 files changed, 75 insertions, 0 deletions
diff --git a/Documentation/btrfstune.asciidoc b/Documentation/btrfstune.asciidoc
new file mode 100644
@@ -0,0 +1,75 @@
+btrfstune - tune various filesystem parameters
+*btrfstune* [options] <dev> [<dev>...]
+*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
+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 (hardlink limit per file in a directory is 65536),
+enabled by mkfs feature 'extref'. Since kernel 3.7.
+Enable skinny metadata extent refs (more efficient representation of extents),
+enabled by mkfs feature 'skinny-metadata'. Since kernel 3.10.
+Enable no-holes feature (more efficient representation of file holes), enabled
+by mkfs feature 'no-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 randomly generated UUID or continue previous fsid change
+operation in case it was interrupted.
+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 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
+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* 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.