View source for Conversion from Ext3/4 and ReiserFS

== Btrfs Conversion from Ext3 or Ext4==

Btrfs has very few pieces of metadata that live in fixed locations, making
it relatively easy to implement an in place conversion utility from other
filesystems.  Copy on write algorithms allow Btrfs to preserve an unmodified
copy of the original FS, and allow administrator to undo the conversion,
even after making changes in the resulting Btrfs filesystem.

The conversion program [[Btrfs-convert|btrfs-convert]] uses libe2fs to read the Ext3/4 metadata, and
uses the free blocks in the Ext3 filesystem to hold the new Btrfs.  The basic
conversion algorithm works like this:

* Duplicate the first 1MB of the device
* Duplicate directories and inodes, creating copies in Btrfs
* Take references on Ext3 file data blocks from the Btrfs files

This does create copies of all the Ext3 metadata, but the Btrfs files
simply point to the same blocks used by the Ext3 files.  This shares the
bulk of the blocks in use between the two filesystems.  Because Btrfs
uses copy on write for all file modifications, the original Ext3 version
of the file data blocks is preserved.

The first 1MB of the device is copied to an alternate location so that
Btrfs metadata may be written there.  Undoing the conversion simply involves
restoring these blocks.

The result of the conversion looks something like this:

[[Image:Converter-description.png]]

The conversion program creates a snapshot in Btrfs that references all of
the blocks used by Ext3, allowing the administrator to control how long the
original Ext3 filesystem is preserved.  If the admin wishes to recover the
space used by Ext3, the snapshot can be deleted and the conversion will be
permanent.

Until the snapshot is deleted, only blocks that were marked as free in Ext3
are used to hold new Btrfs modifications.  This means the conversion can be
undone at any time, restoring the original Ext3 FS.  The converter creates a
sparse file to hold all of the references to the original Ext3 filesystem, and
the offsets in this file correspond to offsets on the block device.  This
allows the admin to mount the image file via readonly loopback and see the
original Ext3 filesystem and the converted Btrfs filesystem at the same
time.

Example Usage:
<pre>
# Always run fsck first
fsck.ext3 -f /dev/xxx

# Convert from Ext3/4->Btrfs
btrfs-convert /dev/xxx

# Mount the resulting Btrfs filesystem
mount -t btrfs /dev/xxx /btrfs

# Mount the ext3/4 snapshot
mount -t btrfs -o subvol=ext2_saved /dev/xxx /ext2_saved

# Loopback mount the image file
mount -t ext3 -o loop,ro /ext2_saved/image /ext3
</pre>

In the example above, the files in /ext3 and in /btrfs will be identical.
Any modifications made in /btrfs will not show up in /ext3.  If you wish
to roll back the conversion:

<pre>
# Completely unmount the Btrfs filesystem
umount /ext3
umount /ext2_saved
umount /btrfs

# roll back the conversion
btrfs-convert -r /dev/xxx

# use the original filesystem
mount -t ext3 /dev/xxx /ext3
</pre>

Or, if you wish to recover the space used by the original Ext3/4 FS and make
the conversion permanent, simply delete /ext2_saved/image.  Once the image is
deleted, the disk will look something like this:

[[Image:Converter-post.png]]

[[Category:Documentation]]