From 26d6392f70a81f179c7b536433bb74395fe4dbc9 Mon Sep 17 00:00:00 2001 From: David Sterba Date: Mon, 2 Nov 2015 14:19:58 +0100 Subject: btrfs-progs: docs: enhance the manual page for convert Signed-off-by: David Sterba --- Documentation/btrfs-convert.asciidoc | 85 ++++++++++++++++++++++++++---------- 1 file changed, 62 insertions(+), 23 deletions(-) (limited to 'Documentation') diff --git a/Documentation/btrfs-convert.asciidoc b/Documentation/btrfs-convert.asciidoc index 09510fa..ca3417f 100644 --- a/Documentation/btrfs-convert.asciidoc +++ b/Documentation/btrfs-convert.asciidoc @@ -3,7 +3,7 @@ btrfs-convert(8) NAME ---- -btrfs-convert - convert from ext2/3/4 filesystem to btrfs or rollback +btrfs-convert - convert from ext2/3/4 filesystem to btrfs SYNOPSIS -------- @@ -11,42 +11,82 @@ SYNOPSIS DESCRIPTION ----------- -*btrfs-convert* is used to convert existed ext2/3/4 to btrfs filesystem, -and the original filesystem image is accessible as from separate subvolume -named 'ext2_saved' as file image. +*btrfs-convert* is used to convert existing ext2/3/4 filesystem image to a +btrfs filesystem in-place. The original filesystem image is accessible +subvolume named 'ext2_saved' as file 'image'. -WARNING: If one hopes to rollback to ext2/3/4, they should not execute -*btrfs balance* command on converted btrfs, since it will change the extent -layout and make *btrfs-convert* unable to rollback. +WARNING: If you are going to perform rollback to ext2/3/4, you should not +execute *btrfs balance* command on the converted filesystem. This will change +the extent layout and make *btrfs-convert* unable to rollback. -NOTE: If one is satisfied with converted btrfs, and not longer wants to -rollback to ext2/3/4, it is highly recommended to remove 'ext2_saved' subvolume -and execute *btrfs filesystem defragment* and *btrfs balance* command on the -converted btrfs. +The conversion utilizes free space of the original filesystem. The exact +estimate of the required space cannot be foretold. The final btrfs metadata +might occupy several gigabytes on a hundreds-gigabyte filesystem. + +If you decide not to rollback anymore, it is recommended to perform a few more +steps to transform the btrfs filesystem to a more compact layout. The +conversion inherits the original data block fragmentation and the metadata +blocks are bound to the original free space layout. + +**REMOVE THE ORIGINAL FILESYSTEM METADATA** + +By removing the 'ext2_saved' subvolume, all metadata of the original filesystem +will be removed: + + # btrfs subvolume delete /mnt/ext2_saved + +At this point it's not possible to do rollback. The filesystem is usable but may +be impacted by the fragmentation. + +**MAKE FILE DATA MORE CONTIGUOUS** + +An optional but recommended step is to run defragmentation on the entire +filesystem. This will attempt to make file extents more contiguous. + + # btrfs filesystem defrag -v -r -f -t 32M /mnt/btrfs + +Verbose recursive defragmentation ('-v', '-r'), flush data per-file ('-f') with target +extent size 32M ('-t'). + +**ATTEMPT TO MAKE BTRFS METADATA MORE COMPACT** + +Optional but recommended step. + +The metadata block groups after conversion may be smaller than the default size +(256MiB or 1GiB). Running a balance will attempt to merge the block groups. +This depends on the free space layout (and fragmentation) and may fail. This is +a soft error leaving the filesystem usable but the block group layout may +remain unchanged. + +Note that balance operation takes a lot of time. + + # btrfs balance start -m /mnt/btrfs OPTIONS ------- -d|--no-datasum:: -Disable data checksum calculations and set NODATASUM file flag. This can speed -up the conversion. +disable data checksum calculations and set NODATASUM file flag, this can speed +up the conversion -i|--no-xattr:: -Ignore xattrs and ACLs. +ignore xattrs and ACLs of files -n|--no-inline:: -Disable inlining of small files to metadata blocks. +disable inlining of small files to metadata blocks, this will decrease the metadata +consumption and may help to convert a filesystem with low free space -N|--nodesize :: -Set filesystem nodesize, the tree block size in which btrfs stores data. +set filesystem nodesize, the tree block size in which btrfs stores its metadata. The default value is 16KB (16384) or the page size, whichever is bigger. -Must be a multiple of the sectorsize, but not larger than 65536. +Must be a multiple of the sectorsize, but not larger than 65536. Se +`mkfs.btrfs`(8) for more details. -r|--rollback:: -Roll back to ext2fs. +rollback to the original ext2/3/4 filesystem if possible -l|--label