path: root/Documentation/btrfs-convert.asciidoc
diff options
authorDimitri John Ledkov <>2016-07-26 13:24:39 +0100
committerDimitri John Ledkov <>2016-07-26 13:24:39 +0100
commit3d69435ee3292b4b1db2d61c4784789d75883821 (patch)
tree2c0edc9d9501374799875af36259089feb99d48c /Documentation/btrfs-convert.asciidoc
Imported Upstream version 4.6.1
Diffstat (limited to 'Documentation/btrfs-convert.asciidoc')
1 files changed, 106 insertions, 0 deletions
diff --git a/Documentation/btrfs-convert.asciidoc b/Documentation/btrfs-convert.asciidoc
new file mode 100644
index 00000000..ab3577db
--- /dev/null
+++ b/Documentation/btrfs-convert.asciidoc
@@ -0,0 +1,106 @@
+btrfs-convert - convert from ext2/3/4 filesystem to btrfs
+*btrfs-convert* [options] <device>
+*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 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.
+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.
+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.
+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').
+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
+disable data checksum calculations and set NODATASUM file flag, this can speed
+up the conversion
+ignore xattrs and ACLs of files
+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 <SIZE>::
+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. See
+`mkfs.btrfs`(8) for more details.
+rollback to the original ext2/3/4 filesystem if possible
+-l|--label <LABEL>::
+set filesystem label during conversion
+use label from the converted filesystem
+-O|--features <feature1>[,<feature2>...]::
+A list of filesystem features turned on at btrfs-convert time. Not all features
+are supported by old kernels. To disable a feature, prefix it with '^'.
+To see all available features that btrfs-convert supports run:
++btrfs-convert -O list-all+
+show progress of conversion, on by default
+disable detailed progress and show only the main phases of conversion
+*btrfs-convert* will return 0 if no error happened.
+If any problems happened, 1 will be returned.