| 1 |
.\" Man page generated from reStructuredText |
| 2 |
.\" by the Docutils 0.22.4 manpage writer. |
| 3 |
. |
| 4 |
. |
| 5 |
.nr rst2man-indent-level 0 |
| 6 |
. |
| 7 |
.de1 rstReportMargin |
| 8 |
\\$1 \\n[an-margin] |
| 9 |
level \\n[rst2man-indent-level] |
| 10 |
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 11 |
- |
| 12 |
\\n[rst2man-indent0] |
| 13 |
\\n[rst2man-indent1] |
| 14 |
\\n[rst2man-indent2] |
| 15 |
.. |
| 16 |
.de1 INDENT |
| 17 |
.\" .rstReportMargin pre: |
| 18 |
. RS \\$1 |
| 19 |
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] |
| 20 |
. nr rst2man-indent-level +1 |
| 21 |
.\" .rstReportMargin post: |
| 22 |
.. |
| 23 |
.de UNINDENT |
| 24 |
. RE |
| 25 |
.\" indent \\n[an-margin] |
| 26 |
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 27 |
.nr rst2man-indent-level -1 |
| 28 |
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 29 |
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u |
| 30 |
.. |
| 31 |
.TH "BTRFS-CONVERT" "8" "May 10, 2026" "7.0" "BTRFS" |
| 32 |
.SH NAME |
| 33 |
btrfs-convert \- convert from ext2/3/4 or reiserfs filesystem to btrfs in-place |
| 34 |
.SH SYNOPSIS |
| 35 |
.sp |
| 36 |
\fBbtrfs\-convert\fP [options] <device> |
| 37 |
.SH DESCRIPTION |
| 38 |
.sp |
| 39 |
The \fBbtrfs\-convert\fP tool can be used to convert existing source filesystem |
| 40 |
image to a btrfs filesystem in\-place. The original filesystem image is |
| 41 |
accessible in subvolume named like \fIext2_saved\fP as file \fIimage\fP\&. |
| 42 |
.sp |
| 43 |
Supported filesystems: |
| 44 |
.INDENT 0.0 |
| 45 |
.IP \(bu 2 |
| 46 |
ext2, ext3, ext4 \-\- original feature, always built in |
| 47 |
.IP \(bu 2 |
| 48 |
reiserfs \-\- since version 4.13, optionally built, requires libreiserfscore 3.6.27 |
| 49 |
.IP \(bu 2 |
| 50 |
NTFS \-\- external tool \%<https://\:github\:.com/\:maharmstone/\:ntfs2btrfs> |
| 51 |
.UNINDENT |
| 52 |
.sp |
| 53 |
The list of supported source filesystem by a given binary is listed at the end |
| 54 |
of help (option \fI\-\-help\fP). |
| 55 |
.sp |
| 56 |
\fBWarning:\fP |
| 57 |
.INDENT 0.0 |
| 58 |
.INDENT 3.5 |
| 59 |
If you are going to perform rollback to the original filesystem, you |
| 60 |
should not execute \fBbtrfs balance\fP command on the converted filesystem. This |
| 61 |
will change the extent layout and make \fBbtrfs\-convert\fP unable to rollback. |
| 62 |
.UNINDENT |
| 63 |
.UNINDENT |
| 64 |
.sp |
| 65 |
The conversion utilizes free space of the original filesystem. The exact |
| 66 |
estimate of the required space cannot be foretold. The final btrfs metadata |
| 67 |
might occupy several gigabytes on a hundreds\-gigabyte filesystem. |
| 68 |
.sp |
| 69 |
If the ability to rollback is no longer important, the it is recommended to |
| 70 |
perform a few more steps to transition the btrfs filesystem to a more compact |
| 71 |
layout. This is because the conversion inherits the original data blocks\(aq |
| 72 |
fragmentation, and also because the metadata blocks are bound to the original |
| 73 |
free space layout. |
| 74 |
.sp |
| 75 |
Due to different constraints, it is only possible to convert filesystems that |
| 76 |
have a supported data block size (i.e. the same that would be valid for |
| 77 |
\fBmkfs.btrfs\fP). This is typically the system page size (4KiB on x86_64 |
| 78 |
machines). |
| 79 |
.sp |
| 80 |
\fBNote:\fP |
| 81 |
.INDENT 0.0 |
| 82 |
.INDENT 3.5 |
| 83 |
Always consider if a mkfs and file copy would not be a better option than |
| 84 |
the in\-place conversion given what was said above. The conversion depends on |
| 85 |
3rd party libraries and the other filesystems could still evolve and add new |
| 86 |
features. Not all combinations are covered or tested. |
| 87 |
.UNINDENT |
| 88 |
.UNINDENT |
| 89 |
.sp |
| 90 |
\fBBEFORE YOU START\fP |
| 91 |
.sp |
| 92 |
The source filesystem must be clean, e.g. no journal to replay or no repairs |
| 93 |
needed. The respective \fBfsck\fP utility must be run on the source filesystem prior |
| 94 |
to conversion. Please refer to the manual pages in case you encounter problems. |
| 95 |
.sp |
| 96 |
For ext2/3/4: |
| 97 |
.INDENT 0.0 |
| 98 |
.INDENT 3.5 |
| 99 |
.sp |
| 100 |
.EX |
| 101 |
# e2fsck \-fvy /dev/sdx |
| 102 |
.EE |
| 103 |
.UNINDENT |
| 104 |
.UNINDENT |
| 105 |
.sp |
| 106 |
For reiserfs: |
| 107 |
.INDENT 0.0 |
| 108 |
.INDENT 3.5 |
| 109 |
.sp |
| 110 |
.EX |
| 111 |
# reiserfsck \-fy /dev/sdx |
| 112 |
.EE |
| 113 |
.UNINDENT |
| 114 |
.UNINDENT |
| 115 |
.sp |
| 116 |
Skipping that step could lead to incorrect results on the target filesystem, |
| 117 |
but it may work. |
| 118 |
.sp |
| 119 |
\fBREMOVE THE ORIGINAL FILESYSTEM METADATA\fP |
| 120 |
.sp |
| 121 |
By removing the subvolume named like \fIext2_saved\fP or \fIreiserfs_saved\fP, all |
| 122 |
metadata of the original filesystem will be removed: |
| 123 |
.INDENT 0.0 |
| 124 |
.INDENT 3.5 |
| 125 |
.sp |
| 126 |
.EX |
| 127 |
# btrfs subvolume delete /mnt/ext2_saved |
| 128 |
.EE |
| 129 |
.UNINDENT |
| 130 |
.UNINDENT |
| 131 |
.sp |
| 132 |
At this point it is not possible to do a rollback. The filesystem is usable but |
| 133 |
may be impacted by the fragmentation inherited from the original filesystem. |
| 134 |
.sp |
| 135 |
\fBMAKE FILE DATA MORE CONTIGUOUS\fP |
| 136 |
.sp |
| 137 |
An optional but recommended step is to run defragmentation on the entire |
| 138 |
filesystem. This will attempt to make file extents more contiguous. |
| 139 |
.INDENT 0.0 |
| 140 |
.INDENT 3.5 |
| 141 |
.sp |
| 142 |
.EX |
| 143 |
# btrfs filesystem defrag \-v \-r \-f \-t 32M /mnt/btrfs |
| 144 |
.EE |
| 145 |
.UNINDENT |
| 146 |
.UNINDENT |
| 147 |
.sp |
| 148 |
Verbose recursive defragmentation (\fI\-v\fP, \fI\-r\fP), flush data per\-file (\fI\-f\fP) with |
| 149 |
target extent size 32MiB (\fI\-t\fP). |
| 150 |
.sp |
| 151 |
\fBATTEMPT TO MAKE BTRFS METADATA MORE COMPACT\fP |
| 152 |
.sp |
| 153 |
Optional but recommended step. |
| 154 |
.sp |
| 155 |
The metadata block groups after conversion may be smaller than the default size |
| 156 |
(256MiB or 1GiB). Running a balance will attempt to merge the block groups. |
| 157 |
This depends on the free space layout (and fragmentation) and may fail due to |
| 158 |
lack of enough work space. This is a soft error leaving the filesystem usable |
| 159 |
but the block group layout may remain unchanged. |
| 160 |
.sp |
| 161 |
Note that balance operation takes a lot of time, please see also |
| 162 |
btrfs\-balance(8) \%<>\&. |
| 163 |
.INDENT 0.0 |
| 164 |
.INDENT 3.5 |
| 165 |
.sp |
| 166 |
.EX |
| 167 |
# btrfs balance start \-m /mnt/btrfs |
| 168 |
.EE |
| 169 |
.UNINDENT |
| 170 |
.UNINDENT |
| 171 |
.SH OPTIONS |
| 172 |
.INDENT 0.0 |
| 173 |
.TP |
| 174 |
.BI \-\-csum \ <type>\fR,\fB \ \-\-checksum \ <type> |
| 175 |
Specify the checksum algorithm. Default is \fIcrc32c\fP\&. Valid values are \fIcrc32c\fP, |
| 176 |
\fIxxhash\fP, \fIsha256\fP or \fIblake2\fP\&. To mount such filesystem kernel must support the |
| 177 |
checksums as well. |
| 178 |
.UNINDENT |
| 179 |
.INDENT 0.0 |
| 180 |
.TP |
| 181 |
.B \-d|\-\-no\-datasum |
| 182 |
disable data checksum calculations and set the NODATASUM file flag, this can speed |
| 183 |
up the conversion |
| 184 |
.TP |
| 185 |
.B \-i|\-\-no\-xattr |
| 186 |
ignore xattrs and ACLs of files |
| 187 |
.TP |
| 188 |
.B \-n|\-\-no\-inline |
| 189 |
disable inlining of small files to metadata blocks, this will decrease the metadata |
| 190 |
consumption and may help to convert a filesystem with low free space |
| 191 |
.TP |
| 192 |
.B \-N|\-\-nodesize <SIZE> |
| 193 |
set filesystem nodesize, the tree block size in which btrfs stores its metadata. |
| 194 |
The default value is 16KiB (16384) or the page size, whichever is bigger. |
| 195 |
Must be a multiple of the sectorsize, but not larger than 65536. See |
| 196 |
mkfs.btrfs(8) \%<> for more details. |
| 197 |
.TP |
| 198 |
.B \-r|\-\-rollback |
| 199 |
rollback to the original ext2/3/4 filesystem if possible |
| 200 |
.TP |
| 201 |
.B \-l|\-\-label <LABEL> |
| 202 |
set filesystem label during conversion |
| 203 |
.TP |
| 204 |
.B \-L|\-\-copy\-label |
| 205 |
use label from the converted filesystem |
| 206 |
.TP |
| 207 |
.B \-O|\-\-features <feature1>[,<feature2>...] |
| 208 |
A list of filesystem features enabled the at time of conversion. Not all features |
| 209 |
are supported by old kernels. To disable a feature, prefix it with \fI^\fP\&. |
| 210 |
Description of the features is in section |
| 211 |
FILESYSTEM FEATURES \%<#\:man-mkfs-filesystem-features> of |
| 212 |
mkfs.btrfs(8) \%<>\&. |
| 213 |
.sp |
| 214 |
To see all available features that btrfs\-convert supports run: |
| 215 |
.INDENT 7.0 |
| 216 |
.INDENT 3.5 |
| 217 |
.sp |
| 218 |
.EX |
| 219 |
btrfs\-convert \-O list\-all |
| 220 |
.EE |
| 221 |
.UNINDENT |
| 222 |
.UNINDENT |
| 223 |
.TP |
| 224 |
.B \-p|\-\-progress |
| 225 |
show progress of conversion (a heartbeat indicator and number of inodes |
| 226 |
processed), on by default |
| 227 |
.UNINDENT |
| 228 |
.INDENT 0.0 |
| 229 |
.TP |
| 230 |
.B \-\-no\-progress |
| 231 |
disable progress and show only the main phases of conversion |
| 232 |
.TP |
| 233 |
.BI \-\-uuid \ <SPEC> |
| 234 |
set the FSID of the new filesystem based on \(aqSPEC\(aq: |
| 235 |
.INDENT 7.0 |
| 236 |
.IP \(bu 2 |
| 237 |
\fInew\fP \- (default) generate UUID for the FSID of btrfs |
| 238 |
.IP \(bu 2 |
| 239 |
\fIcopy\fP \- copy UUID from the source filesystem |
| 240 |
.IP \(bu 2 |
| 241 |
\fIUUID\fP \- a conforming UUID value, the 36 byte string representation |
| 242 |
.UNINDENT |
| 243 |
.TP |
| 244 |
.B \-\-version |
| 245 |
Print the \fBbtrfs\-convert\fP version, builtin features and exit. |
| 246 |
.UNINDENT |
| 247 |
.SH EXIT STATUS |
| 248 |
.sp |
| 249 |
\fBbtrfs\-convert\fP will return 0 if no error happened. |
| 250 |
If any problems happened, 1 will be returned. |
| 251 |
.SH SEE ALSO |
| 252 |
.sp |
| 253 |
mkfs.btrfs(8) \%<> |
| 254 |
.\" End of generated man page. |