diff options
Diffstat (limited to 'Documentation/btrfstune.asciidoc')
| -rw-r--r-- | Documentation/btrfstune.asciidoc | 81 |
1 files changed, 52 insertions, 29 deletions
diff --git a/Documentation/btrfstune.asciidoc b/Documentation/btrfstune.asciidoc index 27100964..1d6bc98d 100644 --- a/Documentation/btrfstune.asciidoc +++ b/Documentation/btrfstune.asciidoc @@ -25,26 +25,29 @@ means. Please refer to the 'FILESYSTEM FEATURES' in `btrfs`(5). 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:: -(since kernel: 3.7) +-f:: +Allow dangerous changes, e.g. clear the seeding flag or change fsid. Make sure +that you are aware of the dangers. + +-m:: +(since kernel: 5.0) + -Enable extended inode refs (hardlink limit per file in a directory is 65536), -enabled by mkfs feature 'extref'. +change fsid stored as 'metadata_uuid' to a randomly generated UUID, +see also '-U' --x:: -(since kernel: 3.10) +-M <UUID>:: +(since kernel: 5.0) + -Enable skinny metadata extent refs (more efficient representation of extents), -enabled by mkfs feature 'skinny-metadata'. +change fsid stored as 'metadata_uuid' to a given UUID, see also '-U' + -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). +The metadata_uuid is stored only in the superblock and is a backward +incompatible change. The fsid in metadata blocks remains unchanged and +is not overwritten, thus the whole operation is significantly faster than +'-U'. ++ +The new metadata_uuid can be used for mount by UUID and is also used to +identify devices of a multi-device filesystem. -n:: (since kernel: 3.14) @@ -52,33 +55,53 @@ the entire filesystem, run a full balance of the metadata. Please refer to 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. +-r:: +(since kernel: 3.7) ++ +Enable extended inode refs (hardlink limit per file in a directory is 65536), +enabled by mkfs feature 'extref'. + +-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. ++ +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. -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'. +Change fsid to 'UUID' in all metadata blocks. + 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'. - ++ +All metadata blocks are rewritten, this may take some time, but the final +filesystem compatibility is unaffected, unlike '-M'. ++ 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. +filesystem temporarily unmountable. To fix it, rerun 'btrfstune -u' 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. +-x:: +(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). EXIT STATUS ----------- |