diff options
| -rw-r--r-- | Documentation/btrfstune.asciidoc | 56 |
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 -------- |