Manpage/btrfs-convert

From btrfs Wiki
(Difference between revisions)
Jump to: navigation, search
(Update from git, v5.14.2)
(remove content)
 
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>&lt;device&gt;</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&#8201;&#8212;&#8201;original feature, always built in
 
</p>
 
</li>
 
<li>
 
<p>
 
reiserfs&#8201;&#8212;&#8201;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>&lt;type&gt;</em>
 
<dt>
 
--checksum <em>&lt;type&gt;</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>&lt;SIZE&gt;</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>&lt;LABEL&gt;</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>&lt;feature1&gt;</em>[,<em>&lt;feature2&gt;</em>&#8230;]
 
<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>&lt;SPEC&gt;</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]]
 

Latest revision as of 12:29, 12 January 2022

Note: manual pages are located at read-the-docs site, please update your links.


Personal tools