1MKFS.BTRFS(8) BTRFS MKFS.BTRFS(8)
2
3
4
6 mkfs.btrfs - create a btrfs filesystem
7
9 mkfs.btrfs [options] <device> [<device>...]
10
12 mkfs.btrfs is used to create the btrfs filesystem on a single or multi‐
13 ple devices. The device is typically a block device but can be a
14 file-backed image as well. Multiple devices are grouped by UUID of the
15 filesystem.
16
17 Before mounting such filesystem, the kernel module must know all the
18 devices either via preceding execution of btrfs device scan or using
19 the device mount option. See section MULTIPLE DEVICES for more details.
20
21 The default block group profiles for data and metadata depend on number
22 of devices and possibly other factors. It's recommended to use specific
23 profiles but the defaults should be OK and allowing future conversions
24 to other profiles. Please see options -d and -m for further details
25 and btrfs-balance(8) for the profile conversion post mkfs.
26
28 -b|--byte-count <size>
29 Specify the size of each device as seen by the filesystem. If
30 not set, the entire device size is used. The total filesystem
31 size will be sum of all device sizes, for a single device
32 filesystem the option effectively specifies the size of the
33 filesystem.
34
35 --csum <type>, --checksum <type>
36 Specify the checksum algorithm. Default is crc32c. Valid values
37 are crc32c, xxhash, sha256 or blake2. To mount such filesystem
38 kernel must support the checksums as well. See CHECKSUM ALGO‐
39 RITHMS in btrfs(5).
40
41 -d|--data <profile>
42 Specify the profile for the data block groups. Valid values are
43 raid0, raid1, raid1c3, raid1c4, raid5, raid6, raid10 or single
44 or dup (case does not matter).
45
46 See DUP PROFILES ON A SINGLE DEVICE for more details.
47
48 On multiple devices, the default was raid0 until version 5.7,
49 while it is single since version 5.8. You can still select raid0
50 manually, but it was not suitable as default.
51
52 -m|--metadata <profile>
53 Specify the profile for the metadata block groups. Valid values
54 are raid0, raid1, raid1c3, raid1c4, raid5, raid6, raid10, single
55 or dup (case does not matter).
56
57 Default on a single device filesystem is DUP and is recommended
58 for metadata in general. The duplication might not be necessary
59 in some use cases and it's up to the user to changed that at
60 mkfs time or later. This depends on hardware that could poten‐
61 tially deduplicate the blocks again but this cannot be detected
62 at mkfs time.
63
64 NOTE:
65 Up to version 5.14 there was a detection of a SSD device
66 (more precisely if it's a rotational device, determined by
67 the contents of file /sys/block/DEV/queue/rotational) that
68 used to select single. This has changed in version 5.15 to be
69 always dup.
70
71 Note that the rotational status can be arbitrarily set by the
72 underlying block device driver and may not reflect the true
73 status (network block device, memory-backed SCSI devices,
74 real block device behind some additional device mapper layer,
75 etc). It's recommended to always set the options
76 --data/--metadata to avoid confusion and unexpected results.
77
78 See DUP PROFILES ON A SINGLE DEVICE for more details.
79
80 On multiple devices the default is raid1.
81
82 -M|--mixed
83 Normally the data and metadata block groups are isolated. The
84 mixed mode will remove the isolation and store both types in the
85 same block group type. This helps to utilize the free space re‐
86 gardless of the purpose and is suitable for small devices. The
87 separate allocation of block groups leads to a situation where
88 the space is reserved for the other block group type, is not
89 available for allocation and can lead to ENOSPC state.
90
91 The recommended size for the mixed mode is for filesystems less
92 than 1GiB. The soft recommendation is to use it for filesystems
93 smaller than 5GiB. The mixed mode may lead to degraded perfor‐
94 mance on larger filesystems, but is otherwise usable, even on
95 multiple devices.
96
97 The nodesize and sectorsize must be equal, and the block group
98 types must match.
99
100 NOTE:
101 Versions up to 4.2.x forced the mixed mode for devices
102 smaller than 1GiB. This has been removed in 4.3+ as it
103 caused some usability issues.
104
105 Mixed profile cannot be used together with other profiles. It
106 can only be set at creation time. Conversion to or from mixed
107 profile is not implemented.
108
109 -n|--nodesize <size>
110 Specify the nodesize, the tree block size in which btrfs stores
111 metadata. The default value is 16KiB (16384) or the page size,
112 whichever is bigger. Must be a multiple of the sectorsize and a
113 power of 2, but not larger than 64KiB (65536). Leafsize always
114 equals nodesize and the options are aliases.
115
116 Smaller node size increases fragmentation but leads to taller
117 b-trees which in turn leads to lower locking contention. Higher
118 node sizes give better packing and less fragmentation at the
119 cost of more expensive memory operations while updating the
120 metadata blocks.
121
122 NOTE:
123 Versions up to 3.11 set the nodesize to 4KiB.
124
125 -s|--sectorsize <size>
126 Specify the sectorsize, the minimum data block allocation unit.
127
128 The default value is the page size and is autodetected. If the
129 sectorsize differs from the page size, the created filesystem
130 may not be mountable by the running kernel. Therefore it is not
131 recommended to use this option unless you are going to mount it
132 on a system with the appropriate page size.
133
134 -L|--label <string>
135 Specify a label for the filesystem. The string should be less
136 than 256 bytes and must not contain newline characters.
137
138 -K|--nodiscard
139 Do not perform whole device TRIM operation on devices that are
140 capable of that. This does not affect discard/trim operation
141 when the filesystem is mounted. Please see the mount option
142 discard for that in btrfs(5).
143
144 -r|--rootdir <rootdir>
145 Populate the toplevel subvolume with files from rootdir. This
146 does not require root permissions to write the new files or to
147 mount the filesystem.
148
149 NOTE:
150 This option may enlarge the image or file to ensure it's big
151 enough to contain the files from rootdir. Since version
152 4.14.1 the filesystem size is not minimized. Please see op‐
153 tion --shrink if you need that functionality.
154
155 --shrink
156 Shrink the filesystem to its minimal size, only works with
157 --rootdir option.
158
159 If the destination block device is a regular file, this option
160 will also truncate the file to the minimal size. Otherwise it
161 will reduce the filesystem available space. Extra space will
162 not be usable unless the filesystem is mounted and resized using
163 btrfs filesystem resize.
164
165 NOTE:
166 Prior to version 4.14.1, the shrinking was done automati‐
167 cally.
168
169 -O|--features <feature1>[,<feature2>...]
170 A list of filesystem features turned on at mkfs time. Not all
171 features are supported by old kernels. To disable a feature,
172 prefix it with ^.
173
174 See section FILESYSTEM FEATURES for more details. To see all
175 available features that mkfs.btrfs supports run:
176
177 $ mkfs.btrfs -O list-all
178
179 -R|--runtime-features <feature1>[,<feature2>...]
180 A list of features that be can enabled at mkfs time, otherwise
181 would have to be turned on on a mounted filesystem. To disable
182 a feature, prefix it with ^.
183
184 See section RUNTIME FEATURES for more details. To see all
185 available runtime features that mkfs.btrfs supports run:
186
187 $ mkfs.btrfs -R list-all
188
189 -f|--force
190 Forcibly overwrite the block devices when an existing filesystem
191 is detected. By default, mkfs.btrfs will utilize libblkid to
192 check for any known filesystem on the devices. Alternatively you
193 can use the wipefs utility to clear the devices.
194
195 -q|--quiet
196 Print only error or warning messages. Options --features or
197 --help are unaffected. Resets any previous effects of --ver‐
198 bose.
199
200 -U|--uuid <UUID>
201 Create the filesystem with the given UUID. The UUID must not ex‐
202 ist on any filesystem currently present.
203
204 -v|--verbose
205 Increase verbosity level, default is 1.
206
207 -V|--version
208 Print the mkfs.btrfs version and exit.
209
210 --help Print help.
211
212 -l|--leafsize <size>
213 Removed in 6.0, used to be alias for --nodesize.
214
216 The default unit is byte. All size parameters accept suffixes in the
217 1024 base. The recognized suffixes are: k, m, g, t, p, e, both upper‐
218 case and lowercase.
219
221 Before mounting a multiple device filesystem, the kernel module must
222 know the association of the block devices that are attached to the
223 filesystem UUID.
224
225 There is typically no action needed from the user. On a system that
226 utilizes a udev-like daemon, any new block device is automatically reg‐
227 istered. The rules call btrfs device scan.
228
229 The same command can be used to trigger the device scanning if the
230 btrfs kernel module is reloaded (naturally all previous information
231 about the device registration is lost).
232
233 Another possibility is to use the mount options device to specify the
234 list of devices to scan at the time of mount.
235
236 # mount -o device=/dev/sdb,device=/dev/sdc /dev/sda /mnt
237
238 NOTE:
239 This means only scanning, if the devices do not exist in the system,
240 mount will fail anyway. This can happen on systems without
241 initramfs/initrd and root partition created with RAID1/10/5/6 pro‐
242 files. The mount action can happen before all block devices are dis‐
243 covered. The waiting is usually done on the initramfs/initrd sys‐
244 tems.
245
246 WARNING:
247 RAID5/6 has known problems and should not be used in production.
248
250 Features that can be enabled during creation time. See also btrfs(5)
251 section FILESYSTEM FEATURES.
252
253 mixed-bg
254 (kernel support since 2.6.37)
255
256 mixed data and metadata block groups, also set by option --mixed
257
258 extref (default since btrfs-progs 3.12, kernel support since 3.7)
259
260 increased hardlink limit per file in a directory to 65536, older
261 kernels supported a varying number of hardlinks depending on the
262 sum of all file name sizes that can be stored into one metadata
263 block
264
265 raid56 (kernel support since 3.9)
266
267 extended format for RAID5/6, also enabled if RAID5 or RAID6
268 block groups are selected
269
270 skinny-metadata
271 (default since btrfs-progs 3.18, kernel support since 3.10)
272
273 reduced-size metadata for extent references, saves a few percent
274 of metadata
275
276 no-holes
277 (default since btrfs-progs 5.15, kernel support since 3.14)
278
279 improved representation of file extents where holes are not ex‐
280 plicitly stored as an extent, saves a few percent of metadata if
281 sparse files are used
282
283 zoned (kernel support since 5.12)
284
285 zoned mode, data allocation and write friendly to
286 zoned/SMR/ZBC/ZNS devices, see ZONED MODE in btrfs(5), the mode
287 is automatically selected when a zoned device is detected
288
290 Features that are typically enabled on a mounted filesystem, e.g. by a
291 mount option or by an ioctl. Some of them can be enabled early, at mkfs
292 time. This applies to features that need to be enabled once and then
293 the status is permanent, this does not replace mount options.
294
295 quota (kernel support since 3.4)
296
297 Enable quota support (qgroups). The qgroup accounting will be
298 consistent, can be used together with --rootdir. See also
299 btrfs-quota(8).
300
301 free-space-tree
302 (default since btrfs-progs 5.15, kernel support since 4.5)
303
304 Enable the free space tree (mount option space_cache=v2) for
305 persisting the free space cache.
306
308 The highlevel organizational units of a filesystem are block groups of
309 three types: data, metadata and system.
310
311 DATA store data blocks and nothing else
312
313 METADATA
314 store internal metadata in b-trees, can store file data if they
315 fit into the inline limit
316
317 SYSTEM store structures that describe the mapping between the physical
318 devices and the linear logical space representing the filesystem
319
320 Other terms commonly used:
321
322 block group, chunk
323 a logical range of space of a given profile, stores data, meta‐
324 data or both; sometimes the terms are used interchangeably
325
326 A typical size of metadata block group is 256MiB (filesystem
327 smaller than 50GiB) and 1GiB (larger than 50GiB), for data it's
328 1GiB. The system block group size is a few megabytes.
329
330 RAID a block group profile type that utilizes RAID-like features on
331 multiple devices: striping, mirroring, parity
332
333 profile
334 when used in connection with block groups refers to the alloca‐
335 tion strategy and constraints, see the section PROFILES for more
336 details
337
339 There are the following block group types available:
340
341 ┌─────────┬─────────────┬────────────┬────────────┬─────────────┬─────────────┐
342 │Profiles │ Redundancy │ Redundancy │ Redundancy │ Space uti‐ │ Min/max de‐ │
343 │ │ │ │ │ lization │ vices │
344 │ │ Copies │ Parity │ Striping │ │ │
345 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
346 │single │ 1 │ │ │ 100% │ 1/any │
347 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
348 │DUP │ 2 / 1 de‐ │ │ │ 50% │ 1/any (see │
349 │ │ vice │ │ │ │ note 1) │
350 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
351 │RAID0 │ 1 │ │ 1 to N │ 100% │ 1/any (see │
352 │ │ │ │ │ │ note 5) │
353 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
354 │RAID1 │ 2 │ │ │ 50% │ 2/any │
355 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
356 │RAID1C3 │ 3 │ │ │ 33% │ 3/any │
357 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
358 │RAID1C4 │ 4 │ │ │ 25% │ 4/any │
359 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
360 │RAID10 │ 2 │ │ 1 to N │ 50% │ 2/any (see │
361 │ │ │ │ │ │ note 5) │
362 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
363 │RAID5 │ 1 │ 1 │ 2 to N-1 │ (N-1)/N │ 2/any (see │
364 │ │ │ │ │ │ note 2) │
365 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
366 │RAID6 │ 1 │ 2 │ 3 to N-2 │ (N-2)/N │ 3/any (see │
367 │ │ │ │ │ │ note 3) │
368 └─────────┴─────────────┴────────────┴────────────┴─────────────┴─────────────┘
369
370 WARNING:
371 It's not recommended to create filesystems with RAID0/1/10/5/6 pro‐
372 files on partitions from the same device. Neither redundancy nor
373 performance will be improved.
374
375 Note 1: DUP may exist on more than 1 device if it starts on a single
376 device and another one is added. Since version 4.5.1, mkfs.btrfs will
377 let you create DUP on multiple devices without restrictions.
378
379 Note 2: It's not recommended to use 2 devices with RAID5. In that case,
380 parity stripe will contain the same data as the data stripe, making
381 RAID5 degraded to RAID1 with more overhead.
382
383 Note 3: It's also not recommended to use 3 devices with RAID6, unless
384 you want to get effectively 3 copies in a RAID1-like manner (but not
385 exactly that).
386
387 Note 4: Since kernel 5.5 it's possible to use RAID1C3 as replacement
388 for RAID6, higher space cost but reliable.
389
390 Note 5: Since kernel 5.15 it's possible to use (mount, convert pro‐
391 files) RAID0 on one device and RAID10 on two devices.
392
393 PROFILE LAYOUT
394 For the following examples, assume devices numbered by 1, 2, 3 and 4,
395 data or metadata blocks A, B, C, D, with possible stripes e.g. A1, A2
396 that would be logically A, etc. For parity profiles PA and QA are par‐
397 ity and syndrome, associated with the given stripe. The simple layouts
398 single or DUP are left out. Actual physical block placement on devices
399 depends on current state of the free/allocated space and may appear
400 random. All devices are assumed to be present at the time of the blocks
401 would have been written.
402
403 RAID1
404 ┌─────────┬──────────┬──────────┬──────────┐
405 │device 1 │ device 2 │ device 3 │ device 4 │
406 ├─────────┼──────────┼──────────┼──────────┤
407 │A │ D │ │ │
408 ├─────────┼──────────┼──────────┼──────────┤
409 │B │ │ │ C │
410 ├─────────┼──────────┼──────────┼──────────┤
411 │C │ │ │ │
412 ├─────────┼──────────┼──────────┼──────────┤
413 │D │ A │ B │ │
414 └─────────┴──────────┴──────────┴──────────┘
415
416 RAID1C3
417 ┌─────────┬──────────┬──────────┬──────────┐
418 │device 1 │ device 2 │ device 3 │ device 4 │
419 ├─────────┼──────────┼──────────┼──────────┤
420 │A │ A │ D │ │
421 ├─────────┼──────────┼──────────┼──────────┤
422 │B │ │ B │ │
423 ├─────────┼──────────┼──────────┼──────────┤
424 │C │ │ A │ C │
425 ├─────────┼──────────┼──────────┼──────────┤
426 │D │ D │ C │ B │
427 └─────────┴──────────┴──────────┴──────────┘
428
429 RAID0
430 ┌─────────┬──────────┬──────────┬──────────┐
431 │device 1 │ device 2 │ device 3 │ device 4 │
432 ├─────────┼──────────┼──────────┼──────────┤
433 │A2 │ C3 │ A3 │ C2 │
434 ├─────────┼──────────┼──────────┼──────────┤
435 │B1 │ A1 │ D2 │ B3 │
436 ├─────────┼──────────┼──────────┼──────────┤
437 │C1 │ D3 │ B4 │ D1 │
438 ├─────────┼──────────┼──────────┼──────────┤
439 │D4 │ B2 │ C4 │ A4 │
440 └─────────┴──────────┴──────────┴──────────┘
441
442 RAID5
443 ┌─────────┬──────────┬──────────┬──────────┐
444 │device 1 │ device 2 │ device 3 │ device 4 │
445 ├─────────┼──────────┼──────────┼──────────┤
446 │A2 │ C3 │ A3 │ C2 │
447 ├─────────┼──────────┼──────────┼──────────┤
448 │B1 │ A1 │ D2 │ B3 │
449 ├─────────┼──────────┼──────────┼──────────┤
450 │C1 │ D3 │ PB │ D1 │
451 ├─────────┼──────────┼──────────┼──────────┤
452 │PD │ B2 │ PC │ PA │
453 └─────────┴──────────┴──────────┴──────────┘
454
455 RAID6
456 ┌─────────┬──────────┬──────────┬──────────┐
457 │device 1 │ device 2 │ device 3 │ device 4 │
458 ├─────────┼──────────┼──────────┼──────────┤
459 │A2 │ QC │ QA │ C2 │
460 ├─────────┼──────────┼──────────┼──────────┤
461 │B1 │ A1 │ D2 │ QB │
462 ├─────────┼──────────┼──────────┼──────────┤
463 │C1 │ QD │ PB │ D1 │
464 └─────────┴──────────┴──────────┴──────────┘
465
466 │PD │ B2 │ PC │ PA │
467 └─────────┴──────────┴──────────┴──────────┘
468
470 The mkfs utility will let the user create a filesystem with profiles
471 that write the logical blocks to 2 physical locations. Whether there
472 are really 2 physical copies highly depends on the underlying device
473 type.
474
475 For example, a SSD drive can remap the blocks internally to a single
476 copy--thus deduplicating them. This negates the purpose of increased
477 redundancy and just wastes filesystem space without providing the ex‐
478 pected level of redundancy.
479
480 The duplicated data/metadata may still be useful to statistically im‐
481 prove the chances on a device that might perform some internal opti‐
482 mizations. The actual details are not usually disclosed by vendors. For
483 example we could expect that not all blocks get deduplicated. This will
484 provide a non-zero probability of recovery compared to a zero chance if
485 the single profile is used. The user should make the tradeoff decision.
486 The deduplication in SSDs is thought to be widely available so the rea‐
487 son behind the mkfs default is to not give a false sense of redundancy.
488
489 As another example, the widely used USB flash or SD cards use a trans‐
490 lation layer between the logical and physical view of the device. The
491 data lifetime may be affected by frequent plugging. The memory cells
492 could get damaged, hopefully not destroying both copies of particular
493 data in case of DUP.
494
495 The wear levelling techniques can also lead to reduced redundancy, even
496 if the device does not do any deduplication. The controllers may put
497 data written in a short timespan into the same physical storage unit
498 (cell, block etc). In case this unit dies, both copies are lost. BTRFS
499 does not add any artificial delay between metadata writes.
500
501 The traditional rotational hard drives usually fail at the sector
502 level.
503
504 In any case, a device that starts to misbehave and repairs from the DUP
505 copy should be replaced! DUP is not backup.
506
508 SMALL FILESYSTEMS AND LARGE NODESIZE
509
510 The combination of small filesystem size and large nodesize is not rec‐
511 ommended in general and can lead to various ENOSPC-related issues dur‐
512 ing mount time or runtime.
513
514 Since mixed block group creation is optional, we allow small filesystem
515 instances with differing values for sectorsize and nodesize to be cre‐
516 ated and could end up in the following situation:
517
518 # mkfs.btrfs -f -n 65536 /dev/loop0
519 btrfs-progs v3.19-rc2-405-g976307c
520 See http://btrfs.wiki.kernel.org for more information.
521
522 Performing full device TRIM (512.00MiB) ...
523 Label: (null)
524 UUID: 49fab72e-0c8b-466b-a3ca-d1bfe56475f0
525 Node size: 65536
526 Sector size: 4096
527 Filesystem size: 512.00MiB
528 Block group profiles:
529 Data: single 8.00MiB
530 Metadata: DUP 40.00MiB
531 System: DUP 12.00MiB
532 SSD detected: no
533 Incompat features: extref, skinny-metadata
534 Number of devices: 1
535 Devices:
536 ID SIZE PATH
537 1 512.00MiB /dev/loop0
538
539 # mount /dev/loop0 /mnt/
540 mount: mount /dev/loop0 on /mnt failed: No space left on device
541
542 The ENOSPC occurs during the creation of the UUID tree. This is caused
543 by large metadata blocks and space reservation strategy that allocates
544 more than can fit into the filesystem.
545
547 btrfs is part of btrfs-progs. Please refer to the documentation at
548 https://btrfs.readthedocs.io or wiki http://btrfs.wiki.kernel.org for
549 further details.
550
552 btrfs(5), btrfs(8), btrfs-balance(8), wipefs(8)
553
554
555
556
5576.1.3 Jan 25, 2023 MKFS.BTRFS(8)