1MKFS.BTRFS(8) BTRFS MKFS.BTRFS(8)
2
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 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 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 --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 -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 See DUP PROFILES ON A SINGLE DEVICE for more details.
47 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 -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 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 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 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 See DUP PROFILES ON A SINGLE DEVICE for more details.
79 On multiple devices the default is raid1.
81 -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 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 The nodesize and sectorsize must be equal, and the block group
98 types must match.
99 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 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 -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 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 NOTE:
123 Versions up to 3.11 set the nodesize to 4KiB.
124 -s|--sectorsize <size>
126 Specify the sectorsize, the minimum data block allocation unit.
127 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 -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 -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 -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 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 --shrink
156 Shrink the filesystem to its minimal size, only works with
157 --rootdir option.
158 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 NOTE:
166 Prior to version 4.14.1, the shrinking was done automati‐
167 cally.
168 -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 See section FILESYSTEM FEATURES for more details. To see all
175 available features that mkfs.btrfs supports run:
176 $ mkfs.btrfs -O list-all
178 -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 See section RUNTIME FEATURES for more details. To see all
185 available runtime features that mkfs.btrfs supports run:
186 $ mkfs.btrfs -R list-all
188 -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 -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 -U|--uuid <UUID>
201 Create the filesystem with the given UUID. The UUID must not ex‐
202 ist on any filesystem currently present.
203 -v|--verbose
205 Increase verbosity level, default is 1.
206 -V|--version
208 Print the mkfs.btrfs version and exit.
209 --help Print help.
211 -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 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 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 Another possibility is to use the mount options device to specify the
234 list of devices to scan at the time of mount.
235 # mount -o device=/dev/sdb,device=/dev/sdc /dev/sda /mnt
237 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 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 mixed-bg
254 (kernel support since 2.6.37)
255 mixed data and metadata block groups, also set by option --mixed
257 extref (default since btrfs-progs 3.12, kernel support since 3.7)
259 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 raid56 (kernel support since 3.9)
266 extended format for RAID5/6, also enabled if RAID5 or RAID6
268 block groups are selected
269 skinny-metadata
271 (default since btrfs-progs 3.18, kernel support since 3.10)
272 reduced-size metadata for extent references, saves a few percent
274 of metadata
275 no-holes
277 (default since btrfs-progs 5.15, kernel support since 3.14)
278 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 zoned (kernel support since 5.12)
284 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 quota (kernel support since 3.4)
296 Enable quota support (qgroups). The qgroup accounting will be
298 consistent, can be used together with --rootdir. See also
299 btrfs-quota(8).
300 free-space-tree
302 (default since btrfs-progs 5.15, kernel support since 4.5)
303 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 DATA store data blocks and nothing else
312 METADATA
314 store internal metadata in b-trees, can store file data if they
315 fit into the inline limit
316 SYSTEM store structures that describe the mapping between the physical
318 devices and the linear logical space representing the filesystem
319 Other terms commonly used:
321 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 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 RAID a block group profile type that utilizes RAID-like features on
331 multiple devices: striping, mirroring, parity
332 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 ┌─────────┬─────────────┬────────────┬────────────┬─────────────┬─────────────┐
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 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 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 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 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 Note 4: Since kernel 5.5 it's possible to use RAID1C3 as replacement
388 for RAID6, higher space cost but reliable.
389 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 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 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 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 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 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 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 │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 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 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 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 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 The traditional rotational hard drives usually fail at the sector
502 level.
503 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 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 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 # 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 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 # mount /dev/loop0 /mnt/
540 mount: mount /dev/loop0 on /mnt failed: No space left on device
541 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)
5536.1.3 Jan 25, 2023 MKFS.BTRFS(8)