NAME
----
-btrfstune - tune various btrfs filesystem parameters
+btrfstune - tune various filesystem parameters
SYNOPSIS
--------
-*btrfstune* [options] <dev> [<dev>...]
+*btrfstune* [options] <device> [<device>...]
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 . Also, the
+manual page `mkfs.btrfs`(8) contains more details about the features.
+
+Some of the features could be also enabled on a mounted filesystem by other
+means. Please refer to the 'FILESYSTEM FEATURES' in `btrfs`(5).
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.
+(since kernel: 3.7)
++
+Enable extended inode refs (hardlink limit per file in a directory is 65536),
+enabled by mkfs feature 'extref'.
+
-x::
-Enable skinny metadata extent refs.
+(since kernel: 3.10)
++
+Enable skinny metadata extent refs (more efficient representation of extents),
+enabled by mkfs feature 'skinny-metadata'.
++
+All newly created extents will use the new representation. To completely switch
+the entire filesystem, run a full balance of the metadata. Please refer to
+`btrfs-balance`(8).
+
+-n::
+(since kernel: 3.14)
++
+Enable no-holes feature (more efficient representation of file holes), enabled
+by mkfs feature 'no-holes'.
+
-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>.
+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.
+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 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 deprecated tool exists for historical reasons but is still in use today.
+Its functionality will be merged to the main tool, at which time *btrfstune*
+will be declared obsolete and scheduled for removal.
SEE ALSO
--------
+`btrfs`(5),
+`btrfs-balance`(8),
`mkfs.btrfs`(8)
projects / platform / upstream / btrfs-progs.git / blobdiff