|
|
| Line 1: |
Line 1: |
| − | =btrfs-convert(8) manual page=
| |
| | {{GeneratedManpage | | {{GeneratedManpage |
| | |name=btrfs-convert}} | | |name=btrfs-convert}} |
| − |
| |
| − | ==NAME==
| |
| − | btrfs-convert - convert from ext2/3/4 or reiserfs filesystem to btrfs in-place
| |
| − |
| |
| − | ==SYNOPSIS==
| |
| − |
| |
| − | <p><b>btrfs-convert</b> [options] <em><device></em></p>
| |
| − | ==DESCRIPTION==
| |
| − |
| |
| − | <p><b>btrfs-convert</b> is used to convert existing source filesystem image to a btrfs
| |
| − | filesystem in-place. The original filesystem image is accessible in subvolume
| |
| − | named like <em>ext2_saved</em> as file <em>image</em>.</p>
| |
| − | <p>Supported filesystems:</p>
| |
| − | <ul>
| |
| − | <li>
| |
| − | <p>
| |
| − | ext2, ext3, ext4 — original feature, always built in
| |
| − | </p>
| |
| − | </li>
| |
| − | <li>
| |
| − | <p>
| |
| − | reiserfs — since version 4.13, optionally built, requires libreiserfscore 3.6.27
| |
| − | </p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>The list of supported source filesystem by a given binary is listed at the end
| |
| − | of help (option <em>--help</em>).</p>
| |
| − | <blockquote><b>Warning:</b>
| |
| − | If you are going to perform rollback to the original filesystem, you
| |
| − | should not execute <b>btrfs balance</b> command on the converted filesystem. This
| |
| − | will change the extent layout and make <b>btrfs-convert</b> unable to rollback.</blockquote>
| |
| − | <p>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.</p>
| |
| − | <p>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.</p>
| |
| − | <p>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
| |
| − | <em>mkfs.btrfs</em>). This is typically the system page size (4KiB on x86_64
| |
| − | machines).</p>
| |
| − | <p><b>BEFORE YOU START</b></p>
| |
| − | <p>The source filesystem must be clean, eg. no journal to replay or no repairs
| |
| − | needed. The respective <em>fsck</em> utility must be run on the source filesytem prior
| |
| − | to conversion. Please refer to the manual pages in case you encounter problems.</p>
| |
| − | <p>For ext2/3/4:</p>
| |
| − | <pre># e2fsck -fvy /dev/sdx</pre>
| |
| − | <p>For reiserfs:</p>
| |
| − | <pre># reiserfsck -fy /dev/sdx</pre>
| |
| − | <p>Skipping that step could lead to incorrect results on the target filesystem,
| |
| − | but it may work.</p>
| |
| − | <p><b>REMOVE THE ORIGINAL FILESYSTEM METADATA</b></p>
| |
| − | <p>By removing the subvolume named like <em>ext2_saved</em> or <em>reiserfs_saved</em>, all
| |
| − | metadata of the original filesystem will be removed:</p>
| |
| − | <pre># btrfs subvolume delete /mnt/ext2_saved</pre>
| |
| − | <p>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.</p>
| |
| − | <p><b>MAKE FILE DATA MORE CONTIGUOUS</b></p>
| |
| − | <p>An optional but recommended step is to run defragmentation on the entire
| |
| − | filesystem. This will attempt to make file extents more contiguous.</p>
| |
| − | <pre># btrfs filesystem defrag -v -r -f -t 32M /mnt/btrfs</pre>
| |
| − | <p>Verbose recursive defragmentation (<em>-v</em>, <em>-r</em>), flush data per-file (<em>-f</em>) with
| |
| − | target extent size 32MiB (<em>-t</em>).</p>
| |
| − | <p><b>ATTEMPT TO MAKE BTRFS METADATA MORE COMPACT</b></p>
| |
| − | <p>Optional but recommended step.</p>
| |
| − | <p>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.</p>
| |
| − | <p>Note that balance operation takes a lot of time, please see also
| |
| − | [[Manpage/btrfs-balance|btrfs-balance(8)]].</p>
| |
| − | <pre># btrfs balance start -m /mnt/btrfs</pre>
| |
| − | ==OPTIONS==
| |
| − |
| |
| − | <dl>
| |
| − | <dt>
| |
| − | --csum <em><type></em>
| |
| − | <dt>
| |
| − | --checksum <em><type></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Specify the checksum algorithm. Default is <em>crc32c</em>. Valid values are <em>crc32c</em>,
| |
| − | <em>xxhash</em>, <em>sha256</em> or <em>blake2</em>. To mount such filesystem kernel must support the
| |
| − | checksums as well.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -d|--no-datasum
| |
| − | <dd>
| |
| − | <p>
| |
| − | disable data checksum calculations and set the NODATASUM file flag, this can speed
| |
| − | up the conversion
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -i|--no-xattr
| |
| − | <dd>
| |
| − | <p>
| |
| − | ignore xattrs and ACLs of files
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -n|--no-inline
| |
| − | <dd>
| |
| − | <p>
| |
| − | 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
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -N|--nodesize <em><SIZE></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | 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
| |
| − | [[Manpage/mkfs.btrfs|mkfs.btrfs(8)]] for more details.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -r|--rollback
| |
| − | <dd>
| |
| − | <p>
| |
| − | rollback to the original ext2/3/4 filesystem if possible
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -l|--label <em><LABEL></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | set filesystem label during conversion
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -L|--copy-label
| |
| − | <dd>
| |
| − | <p>
| |
| − | use label from the converted filesystem
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -O|--features <em><feature1></em>[,<em><feature2></em>…]
| |
| − | <dd>
| |
| − | <p>
| |
| − | 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 <em>^</em>.
| |
| − | Description of the features is in section <em>FILESYSTEM FEATURES</em> of
| |
| − | [[Manpage/mkfs.btrfs|mkfs.btrfs(8)]].
| |
| − | </p>
| |
| − | <p>To see all available features that btrfs-convert supports run:</p>
| |
| − | <p><tt>btrfs-convert -O list-all</tt></p>
| |
| − |
| |
| − | <dt>
| |
| − | -p|--progress
| |
| − | <dd>
| |
| − | <p>
| |
| − | show progress of conversion (a heartbeat indicator and number of inodes
| |
| − | processed), on by default
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | --no-progress
| |
| − | <dd>
| |
| − | <p>
| |
| − | disable progress and show only the main phases of conversion
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | --uuid <em><SPEC></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | set the FSID of the new filesystem based on <em>SPEC</em>:
| |
| − | </p>
| |
| − | <ul>
| |
| − | <li>
| |
| − | <p>
| |
| − | <em>new</em> - (default) generate UUID for the FSID of btrfs
| |
| − | </p>
| |
| − | </li>
| |
| − | <li>
| |
| − | <p>
| |
| − | <em>copy</em> - copy UUID from the source filesystem
| |
| − | </p>
| |
| − | </li>
| |
| − | <li>
| |
| − | <p>
| |
| − | <em>UUID</em> - a conforming UUID value, the 36 byte string representation
| |
| − | </p>
| |
| − | </li>
| |
| − | </ul>
| |
| − |
| |
| − | </dl>
| |
| − | ==EXIT STATUS==
| |
| − |
| |
| − | <p><b>btrfs-convert</b> will return 0 if no error happened.
| |
| − | If any problems happened, 1 will be returned.</p>
| |
| − | ==SEE ALSO==
| |
| − |
| |
| − | <p>[[Manpage/mkfs.btrfs|mkfs.btrfs(8)]]</p>
| |
| − | [[Category:Manpage]]
| |
