X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=Documentation%2Fbtrfstune.asciidoc;h=27100964bc914d3197f800e769ac1f2256f890fb;hb=8c5db79d0f3bd392b2d0965a4444de7726012bee;hp=b6edcb20524ba311bc15051eeb6fdafa285ca5ef;hpb=99ad3805beed9f527830c2d07118718872224e9f;p=platform%2Fupstream%2Fbtrfs-progs.git diff --git a/Documentation/btrfstune.asciidoc b/Documentation/btrfstune.asciidoc index b6edcb2..2710096 100644 --- a/Documentation/btrfstune.asciidoc +++ b/Documentation/btrfstune.asciidoc @@ -3,56 +3,96 @@ btrfstune(8) NAME ---- -btrfstune - tune various btrfs filesystem parameters +btrfstune - tune various filesystem parameters SYNOPSIS -------- -*btrfstune* [options] [...] +*btrfstune* [options] [...] 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 :: -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 :: -Change fsid to . +Change fsid to 'UUID'. + -The 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 - 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)