btrfs-convert(8)

1BTRFS-CONVERT(8)                     BTRFS                    BTRFS-CONVERT(8)
2
3
4

NAME

6       btrfs-convert  -  convert from ext2/3/4 or reiserfs filesystem to btrfs
7       in-place
8

SYNOPSIS

10       btrfs-convert [options] <device>
11

DESCRIPTION

13       The btrfs-convert tool can be used to convert existing source  filesys‐
14       tem  image to a btrfs filesystem in-place.  The original filesystem im‐
15       age is accessible in subvolume named like ext2_saved as file image.
16
17       Supported filesystems:
18
19       • ext2, ext3, ext4 -- original feature, always built in
20
21       • reiserfs -- since version 4.13, optionally built,  requires  libreis‐
22         erfscore 3.6.27
23
24       • ntfs -- external tool https://github.com/maharmstone/ntfs2btrfs
25
26       The  list of supported source filesystem by a given binary is listed at
27       the end of help (option --help).
28
29       WARNING:
30          If you are going to perform rollback to the original filesystem, you
31          should  not  execute btrfs balance command on the converted filesys‐
32          tem. This will change the extent layout and make  btrfs-convert  un‐
33          able to rollback.
34
35       The  conversion utilizes free space of the original filesystem. The ex‐
36       act estimate of the required space cannot be foretold. The final  btrfs
37       metadata might occupy several gigabytes on a hundreds-gigabyte filesys‐
38       tem.
39
40       If the ability to rollback is no longer important,  the  it  is  recom‐
41       mended  to  perform a few more steps to transition the btrfs filesystem
42       to a more compact layout. This is because the conversion  inherits  the
43       original  data  blocks'  fragmentation,  and  also because the metadata
44       blocks are bound to the original free space layout.
45
46       Due to different constraints, it is only possible to  convert  filesys‐
47       tems  that have a supported data block size (ie. the same that would be
48       valid for mkfs.btrfs). This is typically the system page size (4KiB  on
49       x86_64 machines).
50
51       BEFORE YOU START
52
53       The source filesystem must be clean, eg. no journal to replay or no re‐
54       pairs needed. The respective fsck utility must be run on the source fi‐
55       lessytem  prior to conversion. Please refer to the manual pages in case
56       you encounter problems.
57
58       For ext2/3/4:
59
60          # e2fsck -fvy /dev/sdx
61
62       For reiserfs:
63
64          # reiserfsck -fy /dev/sdx
65
66       Skipping that step could  lead  to  incorrect  results  on  the  target
67       filesystem, but it may work.
68
69       REMOVE THE ORIGINAL FILESYSTEM METADATA
70
71       By  removing the subvolume named like ext2_saved or reiserfs_saved, all
72       metadata of the original filesystem will be removed:
73
74          # btrfs subvolume delete /mnt/ext2_saved
75
76       At this point it is not possible to do a rollback.  The  filesystem  is
77       usable  but  may  be  impacted  by the fragmentation inherited from the
78       original filesystem.
79
80       MAKE FILE DATA MORE CONTIGUOUS
81
82       An optional but recommended step is to run defragmentation on  the  en‐
83       tire  filesystem.  This will attempt to make file extents more contigu‐
84       ous.
85
86          # btrfs filesystem defrag -v -r -f -t 32M /mnt/btrfs
87
88       Verbose recursive defragmentation (-v, -r), flush  data  per-file  (-f)
89       with target extent size 32MiB (-t).
90
91       ATTEMPT TO MAKE BTRFS METADATA MORE COMPACT
92
93       Optional but recommended step.
94
95       The  metadata block groups after conversion may be smaller than the de‐
96       fault size (256MiB or 1GiB). Running a balance will  attempt  to  merge
97       the  block groups.  This depends on the free space layout (and fragmen‐
98       tation) and may fail due to lack of enough work space. This is  a  soft
99       error  leaving the filesystem usable but the block group layout may re‐
100       main unchanged.
101
102       Note that balance operation takes  a  lot  of  time,  please  see  also
103       btrfs-balance(8).
104
105          # btrfs balance start -m /mnt/btrfs
106

OPTIONS

108       --csum <type>, --checksum <type>
109              Specify  the checksum algorithm. Default is crc32c. Valid values
110              are crc32c, xxhash, sha256 or blake2. To mount  such  filesystem
111              kernel must support the checksums as well.
112
113       -d|--no-datasum
114              disable  data  checksum  calculations and set the NODATASUM file
115              flag, this can speed up the conversion
116
117       -i|--no-xattr
118              ignore xattrs and ACLs of files
119
120       -n|--no-inline
121              disable inlining of small files to metadata  blocks,  this  will
122              decrease  the  metadata  consumption  and  may help to convert a
123              filesystem with low free space
124
125       -N|--nodesize <SIZE>
126              set filesystem nodesize, the tree  block  size  in  which  btrfs
127              stores  its metadata.  The default value is 16KiB (16384) or the
128              page size, whichever is bigger.  Must be a multiple of the  sec‐
129              torsize,  but  not larger than 65536. See mkfs.btrfs(8) for more
130              details.
131
132       -r|--rollback
133              rollback to the original ext2/3/4 filesystem if possible
134
135       -l|--label <LABEL>
136              set filesystem label during conversion
137
138       -L|--copy-label
139              use label from the converted filesystem
140
141       -O|--features <feature1>[,<feature2>...]
142              A list of filesystem features enabled the at time of conversion.
143              Not all features are supported by old kernels. To disable a fea‐
144              ture, prefix it with ^.  Description of the features is in  sec‐
145              tion FILESYSTEM FEATURES of mkfs.btrfs(8).
146
147              To see all available features that btrfs-convert supports run:
148
149                 btrfs-convert -O list-all+
150
151       -p|--progress
152              show progress of conversion (a heartbeat indicator and number of
153              inodes processed), on by default
154
155       --no-progress
156              disable progress and show only the main phases of conversion
157
158       --uuid <SPEC>
159              set the FSID of the new filesystem based on 'SPEC':
160
161              • new - (default) generate UUID for the FSID of btrfs
162
163              • copy - copy UUID from the source filesystem
164
165              • UUID - a conforming UUID value, the 36 byte string representa‐
166                tion
167

EXIT STATUS

169       btrfs-convert will return 0 if no error happened.  If any problems hap‐
170       pened, 1 will be returned.
171

COPYRIGHT

176       2022
177
178
179
180
1815.18                             May 25, 2022                 BTRFS-CONVERT(8)

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXIT STATUS

SEE ALSO

COPYRIGHT