btrfs-progs: docs: convert btrfs-convert to rst

Signed-off-by: David Sterba <dsterba@suse.com>

Documentation/btrfs-convert.rst

@@ -0,0 +1,165 @@
+btrfs-convert(8)
+================
+
+SYNOPSIS
+--------
+
+**btrfs-convert** [options] <device>
+
+DESCRIPTION
+-----------
+
+**btrfs-convert** is used to convert existing source filesystem image to a btrfs
+filesystem in-place.  The original filesystem image is accessible in subvolume
+named like *ext2_saved* as file *image*.
+
+Supported filesystems:
+
+* ext2, ext3, ext4 -- original feature, always built in
+
+* reiserfs -- since version 4.13, optionally built, requires libreiserfscore 3.6.27
+
+The list of supported source filesystem by a given binary is listed at the end
+of help (option *--help*).
+
+.. warning::
+   If you are going to perform rollback to the original filesystem, 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 the ability to rollback is no longer important, the it is recommended to
+perform a few more steps to transition the btrfs filesystem to a more compact
+layout. This is because the conversion inherits the original data blocks'
+fragmentation, and also because the metadata blocks are bound to the original
+free space layout.
+
+Due to different constraints, it is only possible to convert filesystems that
+have a supported data block size (ie. the same that would be valid for
+**mkfs.btrfs**). This is typically the system page size (4KiB on x86_64
+machines).
+
+**BEFORE YOU START**
+
+The source filesystem must be clean, eg. no journal to replay or no repairs
+needed. The respective **fsck** utility must be run on the source filesytem prior
+to conversion. Please refer to the manual pages in case you encounter problems.
+
+For ext2/3/4:
+
+.. code-block:: bash
+
+    # e2fsck -fvy /dev/sdx
+
+For reiserfs:
+
+.. code-block:: bash
+
+    # reiserfsck -fy /dev/sdx
+
+Skipping that step could lead to incorrect results on the target filesystem,
+but it may work.
+
+**REMOVE THE ORIGINAL FILESYSTEM METADATA**
+
+By removing the subvolume named like *ext2_saved* or *reiserfs_saved*, all
+metadata of the original filesystem will be removed:
+
+.. code-block:: bash
+
+   # btrfs subvolume delete /mnt/ext2_saved
+
+At this point it is not possible to do a rollback. The filesystem is usable but
+may be impacted by the fragmentation inherited from the original filesystem.
+
+**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.
+
+.. code-block:: bash
+
+   # btrfs filesystem defrag -v -r -f -t 32M /mnt/btrfs
+
+Verbose recursive defragmentation (*-v*, *-r*), flush data per-file (*-f*) with
+target extent size 32MiB (*-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 due to
+lack of enough work space. 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, please see also
+``btrfs-balance(8)``.
+
+.. code-block:: bash
+
+   # btrfs balance start -m /mnt/btrfs
+
+OPTIONS
+-------
+
+--csum <type>, --checksum <type>
+        Specify the checksum algorithm. Default is *crc32c*. Valid values are *crc32c*,
+        *xxhash*, *sha256* or *blake2*. To mount such filesystem kernel must support the
+        checksums as well.
+-d|--no-datasum
+        disable data checksum calculations and set the NODATASUM file flag, this can speed
+        up the conversion
+-i|--no-xattr
+        ignore xattrs and ACLs of files
+-n|--no-inline
+        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 16KiB (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.
+-r|--rollback
+        rollback to the original ext2/3/4 filesystem if possible
+-l|--label <LABEL>
+        set filesystem label during conversion
+-L|--copy-label
+        use label from the converted filesystem
+-O|--features <feature1>[,<feature2>...]
+        A list of filesystem features enabled the at time of conversion. Not all features
+        are supported by old kernels. To disable a feature, prefix it with *^*.
+        Description of the features is in section *FILESYSTEM FEATURES* of
+        ``mkfs.btrfs(8)``.
+
+        To see all available features that btrfs-convert supports run:
+
+        .. code-block:: bash
+
+                btrfs-convert -O list-all+
+-p|--progress
+        show progress of conversion (a heartbeat indicator and number of inodes
+        processed), on by default
+--no-progress
+        disable progress and show only the main phases of conversion
+--uuid <SPEC>
+        set the FSID of the new filesystem based on 'SPEC':
+
+        * *new* - (default) generate UUID for the FSID of btrfs
+        * *copy* - copy UUID from the source filesystem
+        * *UUID* - a conforming UUID value, the 36 byte string representation
+
+EXIT STATUS
+-----------
+
+**btrfs-convert** will return 0 if no error happened.
+If any problems happened, 1 will be returned.
+
+SEE ALSO
+--------
+
+``mkfs.btrfs(8)``

Documentation/conf.py

@@ -57,4 +57,5 @@ man_pages = [
     ('btrfs-find-root', 'btrfs-find-root', 'filter to find btrfs root', '', 8),
     ('btrfs-filesystem', 'btrfs-filesystem', 'command group that primarily does work on the whole filesystems', '', 8),
     ('btrfs-device', 'btrfs-device', 'manage devices of btrfs filesystems', '', 8),
+    ('btrfs-convert', 'btrfs-convert', 'convert from ext2/3/4 or reiserfs filesystem to btrfs in-place', '', 8),
 ]

Documentation/man-index.rst

@@ -6,6 +6,7 @@ Manual pages
 .. toctree::
    :maxdepth: 1
 
+   btrfs-convert
    btrfs-device
    btrfs-filesystem
    btrfs-find-root