Debian Codegraph @

upstream/debian-trixie/man8/mkfs.btrfs.8

raw
1 '\" t
2 .\" Man page generated from reStructuredText.
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 "MKFS.BTRFS" "8" "May 18, 2026" "7.0" "BTRFS"
32 .SH NAME
33 mkfs.btrfs \- create a btrfs filesystem
34 .SH SYNOPSIS
35 .sp
36 \fBmkfs.btrfs\fP [options] <device> [<device>...]
37 .SH DESCRIPTION
38 .sp
39 \fBmkfs.btrfs\fP is used to create the btrfs filesystem on a single or multiple
40 devices. The \fIdevice\fP is typically a block device but can be a file\-backed image
41 as well. Multiple devices are grouped by UUID of the filesystem.
42 .sp
43 Before mounting such filesystem, the kernel module must know all the devices
44 either via preceding execution of \fBbtrfs device scan\fP or using the \fIdevice\fP
45 mount option. See section \fI\%MULTIPLE DEVICES\fP
46 for more details.
47 .sp
48 The default block group profiles for data and metadata depend on number of
49 devices and possibly other factors. It\(aqs recommended to use specific profiles
50 but the defaults should be OK and allowing future conversions to other profiles.
51 Please see options \fI\-d\fP and \fI\-m\fP for further details and \fI\%btrfs\-balance(8)\fP for
52 the profile conversion post mkfs.
53 .SH OPTIONS
54 .INDENT 0.0
55 .TP
56 .B \-b|\-\-byte\-count <size>
57 Specify the size of each device as seen by the filesystem. If not set,
58 the entire device size is used. The total filesystem size will be the sum
59 of all device sizes, for a single device filesystem the option
60 effectively specifies the size of the filesystem.
61 .UNINDENT
62 .INDENT 0.0
63 .TP
64 .BI \-\-csum \ <type>\fR,\fB \ \-\-checksum \ <type>
65 Specify the checksum algorithm. Default is \fIcrc32c\fP\&. Valid values are \fIcrc32c\fP,
66 \fIxxhash\fP, \fIsha256\fP or \fIblake2\fP\&. To mount such filesystem kernel must support the
67 checksums as well. See section \fI\%CHECKSUM ALGORITHMS\fP
68 in \fI\%btrfs(5)\fP\&.
69 .UNINDENT
70 .INDENT 0.0
71 .TP
72 .B \-d|\-\-data <profile>
73 Specify the profile for the data block groups. Valid values are \fIraid0\fP,
74 \fIraid1\fP, \fIraid1c3\fP, \fIraid1c4\fP, \fIraid5\fP, \fIraid6\fP, \fIraid10\fP or \fIsingle\fP or \fIdup\fP
75 (case does not matter).
76 .sp
77 See section \fI\%DUP PROFILES ON A SINGLE DEVICE\fP
78 for more details.
79 .sp
80 On multiple devices, the default was \fIraid0\fP until version 5.7, while it is
81 \fIsingle\fP since version 5.8. You can still select \fIraid0\fP manually, but it was not
82 suitable as default.
83 .TP
84 .B \-m|\-\-metadata <profile>
85 Specify the profile for the metadata block groups.
86 Valid values are \fIraid0\fP, \fIraid1\fP, \fIraid1c3\fP, \fIraid1c4\fP, \fIraid5\fP, \fIraid6\fP,
87 \fIraid10\fP, \fIsingle\fP or \fIdup\fP (case does not matter).
88 .sp
89 Default on a single device filesystem is \fIDUP\fP and is recommended for metadata
90 in general. The duplication might not be necessary in some use cases and it\(aqs
91 up to the user to change that at mkfs time or later. This depends on hardware
92 that could potentially deduplicate the blocks again but this cannot be detected
93 at mkfs time.
94 .sp
95 \fBNOTE:\fP
96 .INDENT 7.0
97 .INDENT 3.5
98 Up to version 5.14 there was a detection of a SSD device (more precisely
99 if it\(aqs a rotational device, determined by the contents of file
100 \fB/sys/block/DEV/queue/rotational\fP) that used to select \fIsingle\fP\&. This has
101 changed in version 5.15 to be always \fIdup\fP\&.
102 .sp
103 Note that the rotational status can be arbitrarily set by the underlying block
104 device driver and may not reflect the true status (network block device, memory\-backed
105 SCSI devices, real block device behind some additional device mapper layer,
106 etc). It\(aqs recommended to always set the options \fI\-\-data/\-\-metadata\fP to avoid
107 confusion and unexpected results.
108 .sp
109 See section \fI\%DUP PROFILES ON A SINGLE DEVICE\fP
110 for more details.
111 .UNINDENT
112 .UNINDENT
113 .sp
114 On multiple devices the default is \fIraid1\fP\&.
115 .UNINDENT
116 .INDENT 0.0
117 .TP
118 .B \-M|\-\-mixed
119 Normally the data and metadata block groups are isolated. The \fImixed\fP mode
120 will remove the isolation and store both types in the same block group type.
121 This helps to utilize the free space regardless of the purpose and is suitable
122 for small devices. The separate allocation of block groups leads to a situation
123 where the space is reserved for the other block group type, is not available for
124 allocation and can lead to ENOSPC state.
125 .sp
126 The recommended size for the mixed mode is for filesystems less than 1GiB. The
127 soft recommendation is to use it for filesystems smaller than 5GiB. The mixed
128 mode may lead to degraded performance on larger filesystems, but is otherwise
129 usable, even on multiple devices.
130 .sp
131 The \fInodesize\fP and \fIsectorsize\fP must be equal, and the block group types must
132 match.
133 .sp
134 \fBNOTE:\fP
135 .INDENT 7.0
136 .INDENT 3.5
137 Versions up to 4.2.x forced the mixed mode for devices smaller than 1GiB.
138 This has been removed in 4.3+ as it caused some usability issues.
139 .sp
140 Mixed profile cannot be used together with other profiles. It can only
141 be set at creation time. Conversion to or from mixed profile is not
142 implemented.
143 .UNINDENT
144 .UNINDENT
145 .TP
146 .B \-n|\-\-nodesize <size>
147 Specify the nodesize, the tree block size in which btrfs stores metadata. The
148 default value is 16KiB (16384) or the page size, whichever is bigger. Must be a
149 multiple of the sectorsize and a power of 2, but not larger than 64KiB (65536).
150 Leafsize always equals nodesize and the options are aliases.
151 .sp
152 Smaller node size increases fragmentation but leads to taller b\-trees which in
153 turn leads to lower locking contention. Higher node sizes give better packing
154 and less fragmentation at the cost of more expensive memory operations while
155 updating the metadata blocks.
156 .sp
157 \fBNOTE:\fP
158 .INDENT 7.0
159 .INDENT 3.5
160 Versions up to 3.11 set the nodesize to 4KiB.
161 .UNINDENT
162 .UNINDENT
163 .TP
164 .B \-s|\-\-sectorsize <size>
165 Specify the sectorsize, the minimum data block allocation unit.
166 .sp
167 \fBNOTE:\fP
168 .INDENT 7.0
169 .INDENT 3.5
170 Versions prior to 6.7 set the sectorsize matching the host CPU
171 page size, starting in 6.7 this is 4KiB for cross\-architecture
172 compatibility. Please read more about the \fI\%subpage block size support\fP
173 and \fI\%its status\fP\&.
174 .UNINDENT
175 .UNINDENT
176 .sp
177 By default, the value is 4KiB, but it can be manually set to match the
178 system page size (e.g. using command \fBgetconf PAGE_SIZE\fP).
179 However, if the sector size is different from the page
180 size, the resulting filesystem may not be mountable by the current
181 kernel, apart from the default 4KiB. Hence, using this option is not
182 advised unless you intend to mount it on a system with the suitable
183 page size.
184 .sp
185 In experimental build the size 2K (2048) is also allowed and needs
186 kernel that also allows that value, then it works in the subpage mode.
187 .TP
188 .B \-L|\-\-label <string>
189 Specify a label for the filesystem. The \fIstring\fP should be less than 256
190 bytes and must not contain newline characters.
191 .TP
192 .B \-K|\-\-nodiscard
193 Do not perform whole device TRIM operation on devices that are capable of that.
194 This does not affect discard/trim operation when the filesystem is mounted.
195 Please see the mount option \fIdiscard\fP for that in \fI\%btrfs(5)\fP\&.
196 .TP
197 .B \-r|\-\-rootdir <rootdir>
198 Populate the toplevel subvolume with files from \fIrootdir\fP\&. This does not
199 require root permissions to write the new files or to mount the filesystem.
200 .sp
201 Directories can be created as subvolumes, see also option \fI\-\-subvol\fP\&.
202 Hardlinks are detected and created in the filesystem image.
203 .sp
204 \fBNOTE:\fP
205 .INDENT 7.0
206 .INDENT 3.5
207 This option may enlarge the image or file to ensure it\(aqs big enough to
208 contain the files from \fIrootdir\fP\&. Since version 4.14.1 the filesystem size is
209 not minimized. Please see option \fI\-\-shrink\fP if you need that functionality.
210 .UNINDENT
211 .UNINDENT
212 .TP
213 .B \-\-compress <algo>[:<level>]
214 Try to compress files when using \fI\-\-rootdir\fP\&. Supported values for \fIalgo\fP are
215 \fIno\fP (the default), \fIzstd\fP, \fIlzo\fP or \fIzlib\fP\&. The optional value \fIlevel\fP is a
216 compression level, 1..15 for \fIzstd\fP, 1..9 for \fIzlib\fP\&.
217 .sp
218 It is recommended to use the highest level to achieve maximum space savings.
219 Compression at mkfs time is not as constrained as in kernel where it\(aqs
220 desirable to use less CPU load. Otherwise the default level is 3.
221 .sp
222 As with the kernel, \fBmkfs.btrfs\fP won\(aqt write compressed extents when
223 they would be larger than the uncompressed versions, and will set file attribute
224 \fINOCOMPRESS\fP if its beginning is found to be incompressible.
225 .sp
226 \fBNOTE:\fP
227 .INDENT 7.0
228 .INDENT 3.5
229 The support for ZSTD and LZO is a compile\-time option, please check
230 the output of \fBmkfs.btrfs \-\-version\fP for the actual support.
231 .UNINDENT
232 .UNINDENT
233 .TP
234 .B \-u|\-\-subvol <type>:<subdir>
235 Specify that \fIsubdir\fP is to be created as a subvolume rather than a regular
236 directory. The option \fI\-\-rootdir\fP must also be specified, and \fIsubdir\fP must be an
237 existing subdirectory within it. This option can be specified multiple times.
238 .sp
239 The \fItype\fP is an optional additional modifier. Valid choices are:
240 .INDENT 7.0
241 .IP \(bu 2
242 \fIdefault\fP: create as default subvolume
243 .IP \(bu 2
244 \fIro\fP: create as read\-only subvolume
245 .IP \(bu 2
246 \fIrw\fP: create as read\-write subvolume (the default)
247 .IP \(bu 2
248 \fIdefault\-ro\fP: create as read\-only default subvolume
249 .UNINDENT
250 .sp
251 Only one of \fIdefault\fP and \fIdefault\-ro\fP may be specified.
252 .sp
253 If you wish to create a subvolume with a name containing a colon and you don\(aqt
254 want this to be parsed as containing a modifier, you can prefix the path with \fB\&./\fP:
255 .INDENT 7.0
256 .INDENT 3.5
257 .sp
258 .EX
259 $ mkfs.btrfs \-\-rootdir dir \-\-subvol ./ro:subdir /dev/loop0
260 .EE
261 .UNINDENT
262 .UNINDENT
263 .sp
264 If there are hardlinks inside \fIrootdir\fP and \fIsubdir\fP will split the
265 subvolumes, like the following case:
266 .INDENT 7.0
267 .INDENT 3.5
268 .sp
269 .EX
270 rootdir/
271 |\- hardlink1
272 |\- hardlink2
273 |\- subdir/ <\- will be a subvolume
274 |\- hardlink3
275 .EE
276 .UNINDENT
277 .UNINDENT
278 .sp
279 In that case we cannot create \fBhardlink3\fP as hardlinks of
280 \fBhardlink1\fP and \fBhardlink2\fP because \fBhardlink3\fP will
281 be inside a new subvolume.
282 .TP
283 .B \-\-inode\-flags <flags>:<path>
284 Specify that \fIpath\fP to have inode \fIflags\fP, other than the default one (which
285 implies data COW and data checksum). The option \fI\-\-rootdir\fP must also be
286 specified. This option can be specified multiple times.
287 .sp
288 The supported flag(s) are:
289 .INDENT 7.0
290 .IP \(bu 2
291 \fInodatacow\fP: disable data COW, implies \fInodatasum\fP for regular files.
292 .IP \(bu 2
293 \fInodatasum\fP: disable data checksum only.
294 .UNINDENT
295 .sp
296 \fIflags\fP can be separated by comma (\fI,\fP).
297 .sp
298 Children inodes will inherit the flags from their parent inodes, like the
299 following case:
300 .INDENT 7.0
301 .INDENT 3.5
302 .sp
303 .EX
304 rootdir/
305 |\- file1
306 |\- file2
307 |\- dir/
308 |\- file3
309 .EE
310 .UNINDENT
311 .UNINDENT
312 .sp
313 In that case, if \fI\-\-inode\-flags nodatacow:dir\fP is specified, both
314 \fBdir\fP and \fBfile3\fP will have the \fInodatacow\fP flag.
315 .sp
316 And this option also works with \fI\-\-subvol\fP option, but the inode flag of
317 each subvolume is independent and will not inherit from the parent directory.
318 (The same as the kernel behavior.)
319 .UNINDENT
320 .INDENT 0.0
321 .TP
322 .B \-\-reflink
323 When used with \fI\-\-rootdir\fP try to clone file extents using FICLONERANGE
324 ioctl instead of copying the bytes. This requires the source files and
325 the final image to exist on the same filesystem.
326 .TP
327 .B \-\-shrink
328 Shrink the filesystem to its minimal size, only works with \fI\-\-rootdir\fP option.
329 .sp
330 If the destination block device is a regular file, this option will also
331 truncate the file to the minimal size. Otherwise it will reduce the filesystem
332 available space. Extra space will not be usable unless the filesystem is
333 mounted and resized using \fBbtrfs filesystem resize\fP\&.
334 .sp
335 \fBNOTE:\fP
336 .INDENT 7.0
337 .INDENT 3.5
338 Prior to version 4.14.1, the shrinking was done automatically.
339 .UNINDENT
340 .UNINDENT
341 .UNINDENT
342 .INDENT 0.0
343 .TP
344 .B \-O|\-\-features <feature1>[,<feature2>...]
345 A list of filesystem features turned on at mkfs time. Not all features are
346 supported by old kernels. To disable a feature, prefix it with \fI^\fP\&.
347 .sp
348 See section \fI\%FILESYSTEM FEATURES\fP
349 for more details. To see all available features that
350 \fBmkfs.btrfs\fP supports run:
351 .INDENT 7.0
352 .INDENT 3.5
353 .sp
354 .EX
355 $ mkfs.btrfs \-O list\-all
356 .EE
357 .UNINDENT
358 .UNINDENT
359 .TP
360 .B \-f|\-\-force
361 Forcibly overwrite the block devices when an existing filesystem is detected.
362 By default, \fBmkfs.btrfs\fP will utilize \fIlibblkid\fP to check for any known
363 filesystem on the devices. Alternatively you can use the \fBwipefs\fP utility
364 to clear the devices.
365 .TP
366 .B \-q|\-\-quiet
367 Print only error or warning messages. Options \fI\-\-features\fP or \fI\-\-help\fP are unaffected.
368 Resets any previous effects of \fI\-\-verbose\fP\&.
369 .TP
370 .B \-U|\-\-uuid <UUID>
371 Create the filesystem with the given \fIUUID\fP\&. For a single\-device filesystem,
372 you can duplicate the UUID. However, for a multi\-device filesystem, the UUID
373 must not already exist on any currently present filesystem.
374 .UNINDENT
375 .INDENT 0.0
376 .TP
377 .BI \-\-device\-uuid \ <UUID>
378 Create the filesystem with the given device\-uuid \fIUUID\fP (also known as
379 UUID_SUB in \fBblkid\fP). For a single device filesystem, you can
380 duplicate the device\-uuid. However, used for a multi\-device filesystem
381 this option will not work at the moment.
382 .UNINDENT
383 .INDENT 0.0
384 .TP
385 .B \-v|\-\-verbose
386 Increase verbosity level, default is 1.
387 .TP
388 .B \-V|\-\-version
389 Print the \fBmkfs.btrfs\fP version, builtin features and exit.
390 .UNINDENT
391 .INDENT 0.0
392 .TP
393 .B \-\-help
394 Print help.
395 .UNINDENT
396 .SH DEPRECATED OPTIONS
397 .INDENT 0.0
398 .TP
399 .B \-R|\-\-runtime\-features <feature1>[,<feature2>...]
400 Removed in 6.3, was used to specify features not affecting on\-disk format.
401 Now all such features are merged into \fI\-O|\-\-features\fP option. The option
402 \-R will stay for backward compatibility.
403 .UNINDENT
404 .SH SIZE UNITS
405 .sp
406 The default unit is \fIbyte\fP\&. All size parameters accept suffixes in the 1024
407 base. The recognized suffixes are: \fIk\fP, \fIm\fP, \fIg\fP, \fIt\fP, \fIp\fP, \fIe\fP, both uppercase
408 and lowercase.
409 .SH MULTIPLE DEVICES
410 .sp
411 Before mounting a multiple device filesystem, the kernel module must know the
412 association of the block devices that are attached to the filesystem UUID.
413 .sp
414 There is typically no action needed from the user. On a system that utilizes a
415 udev\-like daemon, any new block device is automatically registered. The rules
416 call \fBbtrfs device scan\fP\&.
417 .sp
418 The same command can be used to trigger the device scanning if the btrfs kernel
419 module is reloaded (naturally all previous information about the device
420 registration is lost).
421 .sp
422 Another possibility is to use the mount options \fIdevice\fP to specify the list of
423 devices to scan at the time of mount.
424 .INDENT 0.0
425 .INDENT 3.5
426 .sp
427 .EX
428 # mount \-o device=/dev/sdb,device=/dev/sdc /dev/sda /mnt
429 .EE
430 .UNINDENT
431 .UNINDENT
432 .sp
433 \fBNOTE:\fP
434 .INDENT 0.0
435 .INDENT 3.5
436 This means only scanning, if the devices do not exist in the system,
437 mount will fail anyway. This can happen on systems without initramfs/initrd and
438 root partition created with RAID1/10/5/6 profiles. The mount action can happen
439 before all block devices are discovered. The waiting is usually done on the
440 initramfs/initrd systems.
441 .UNINDENT
442 .UNINDENT
443 .sp
444 \fBWARNING:\fP
445 .INDENT 0.0
446 .INDENT 3.5
447 RAID5/6 has known problems and should not be used in production.
448 .UNINDENT
449 .UNINDENT
450 .SH FILESYSTEM FEATURES
451 .sp
452 Features that can be enabled during creation time. See also \fI\%btrfs(5)\fP section
453 \fI\%FILESYSTEM FEATURES\fP\&.
454 .INDENT 0.0
455 .TP
456 .B mixed\-bg
457 (kernel support since 2.6.37)
458 .sp
459 mixed data and metadata block groups, also set by option \fI\-\-mixed\fP
460 .UNINDENT
461 .INDENT 0.0
462 .TP
463 .B extref
464 (default since btrfs\-progs 3.12, kernel support since 3.7)
465 .sp
466 increased hardlink limit per file in a directory to 65536, older kernels
467 supported a varying number of hardlinks depending on the sum of all file name
468 sizes that can be stored into one metadata block
469 .TP
470 .B raid56
471 (kernel support since 3.9)
472 .sp
473 extended format for RAID5/6, also enabled if RAID5 or RAID6 block groups
474 are selected
475 .UNINDENT
476 .INDENT 0.0
477 .TP
478 .B skinny\-metadata
479 (default since btrfs\-progs 3.18, kernel support since 3.10)
480 .sp
481 reduced\-size metadata for extent references, saves a few percent of metadata
482 .UNINDENT
483 .INDENT 0.0
484 .TP
485 .B no\-holes
486 (default since btrfs\-progs 5.15, kernel support since 3.14)
487 .sp
488 improved representation of file extents where holes are not explicitly
489 stored as an extent, saves a few percent of metadata if sparse files are used
490 .TP
491 .B zoned
492 (kernel support since 5.12)
493 .sp
494 zoned mode, data allocation and write friendly to zoned/SMR/ZBC/ZNS devices,
495 see \fI\%ZONED MODE\fP in
496 \fI\%btrfs(5)\fP, the mode is automatically selected when a
497 zoned device is detected
498 .TP
499 .B quota
500 (kernel support since 3.4)
501 .sp
502 Enable quota support (qgroups). The qgroup accounting will be consistent,
503 can be used together with \fI\-\-rootdir\fP\&. See also \fI\%btrfs\-quota(8)\fP\&.
504 .UNINDENT
505 .INDENT 0.0
506 .TP
507 .B free\-space\-tree
508 (default since btrfs\-progs 5.15, kernel support since 4.5)
509 .sp
510 Enable the free space tree (mount option \fIspace_cache=v2\fP) for persisting the
511 free space cache in a b\-tree. This is built on top of the COW mechanism
512 and has better performance than v1.
513 .sp
514 Offline conversion from filesystems that don\(aqt have this feature
515 enabled at \fImkfs\fP time is possible, see \fI\%btrfstune(8)\fP\&.
516 .sp
517 Online conversion can be done by mounting with \fBspace_cache=v2\fP, this
518 is sufficient to be done one time.
519 .UNINDENT
520 .INDENT 0.0
521 .TP
522 .B block\-group\-tree
523 (default since btrfs\-progs v6.19, kernel support since 6.1)
524 .sp
525 Enable a dedicated b\-tree for block group items, this greatly reduces
526 mount time for large filesystems due to better data locality that
527 avoids seeking. On rotational devices the \fIlarge\fP size is considered
528 starting from the 2\-4TiB. Can be used on other types of devices (SSD,
529 NVMe, ...) as well.
530 .sp
531 Offline conversion from filesystems that don\(aqt have this feature
532 enabled at \fImkfs\fP time is possible, see \fI\%btrfstune(8)\fP\&. Online
533 conversion is not possible.
534 .sp
535 \fBNOTE:\fP
536 .INDENT 7.0
537 .INDENT 3.5
538 This feature requires \fBno\-holes\fP and \fBfree\-space\-tree\fP
539 features, if these dependency features are disabled,
540 \fBblock\-group\-tree\fP feature will also be disabled automatically.
541 .UNINDENT
542 .UNINDENT
543 .UNINDENT
544 .INDENT 0.0
545 .TP
546 .B raid\-stripe\-tree
547 (kernel support since 6.7, CONFIG_BTRFS_DEBUG/CONFIG_BTRFS_EXPERIMENTAL)
548 .sp
549 Separate tree for logical file extent mapping where the physical mapping
550 may not match on multiple devices. This is now used in zoned mode to
551 implement RAID0/RAID1* profiles, but can be used in non\-zoned mode as
552 well. The support for RAID56 is in development and will eventually
553 fix the problems with the current implementation. This is a backward
554 incompatible feature and has to be enabled at mkfs time.
555 .sp
556 \fBNOTE:\fP
557 .INDENT 7.0
558 .INDENT 3.5
559 Due to the status of implementation it is enabled only in
560 builds with CONFIG_BTRFS_DEBUG/CONFIG_BTRFS_EXPERIMENTAL.
561 Support by the kernel module can be found in the sysfs feature
562 list.
563 .UNINDENT
564 .UNINDENT
565 .TP
566 .B squota
567 (kernel support since 6.7)
568 .sp
569 Enable simple quota accounting (squotas). This is an alternative to
570 qgroups with a smaller performance impact but no notion of shared vs.
571 exclusive usage.
572 .UNINDENT
573 .SH BLOCK GROUPS, CHUNKS, RAID
574 .sp
575 The highlevel organizational units of a filesystem are block groups of three types:
576 data, metadata and system.
577 .INDENT 0.0
578 .TP
579 .B DATA
580 store data blocks and nothing else
581 .TP
582 .B METADATA
583 store internal metadata in b\-trees, can store file data if they fit into the
584 inline limit
585 .TP
586 .B SYSTEM
587 store structures that describe the mapping between the physical devices and the
588 linear logical space representing the filesystem
589 .UNINDENT
590 .sp
591 Other terms commonly used:
592 .INDENT 0.0
593 .TP
594 .B block group, chunk
595 a logical range of space of a given profile, stores data, metadata or both;
596 sometimes the terms are used interchangeably
597 .sp
598 A typical size of metadata block group is 256MiB (filesystem smaller than
599 50GiB) and 1GiB (larger than 50GiB), for data it\(aqs 1GiB. The system block group
600 size is a few megabytes.
601 .TP
602 .B RAID
603 a block group profile type that utilizes RAID\-like features on multiple
604 devices: striping, mirroring, parity
605 .TP
606 .B profile
607 when used in connection with block groups refers to the allocation strategy
608 and constraints, see the section \fI\%PROFILES\fP for more details
609 .UNINDENT
610 .SH PROFILES
611 .sp
612 There are the following block group types available:
613 .TS
614 box center;
615 l|l|l|l|l|l.
616 T{
617 Profiles
618 T} T{
619 Redundancy
620 .sp
621 Copies
622 T} T{
623 Redundancy
624 .sp
625 Parity
626 T} T{
627 Redundancy
628 .sp
629 Striping
630 T} T{
631 Space utilization
632 T} T{
633 Min/max devices
634 T}
635 _
636 T{
637 single
638 T} T{
639 1
640 T} T{
641 T} T{
642 T} T{
643 100%
644 T} T{
645 1/any
646 T}
647 _
648 T{
649 DUP
650 T} T{
651 2 / 1 device
652 T} T{
653 T} T{
654 T} T{
655 50%
656 T} T{
657 1/any (see note 1)
658 T}
659 _
660 T{
661 RAID0
662 T} T{
663 1
664 T} T{
665 T} T{
666 1 to N
667 T} T{
668 100%
669 T} T{
670 1/any (see note 5)
671 T}
672 _
673 T{
674 RAID1
675 T} T{
676 2
677 T} T{
678 T} T{
679 T} T{
680 50%
681 T} T{
682 2/any
683 T}
684 _
685 T{
686 RAID1C3
687 T} T{
688 3
689 T} T{
690 T} T{
691 T} T{
692 33%
693 T} T{
694 3/any
695 T}
696 _
697 T{
698 RAID1C4
699 T} T{
700 4
701 T} T{
702 T} T{
703 T} T{
704 25%
705 T} T{
706 4/any
707 T}
708 _
709 T{
710 RAID10
711 T} T{
712 2
713 T} T{
714 T} T{
715 1 to N
716 T} T{
717 50%
718 T} T{
719 2/any (see note 5)
720 T}
721 _
722 T{
723 RAID5
724 T} T{
725 1
726 T} T{
727 1
728 T} T{
729 2 to N\-1
730 T} T{
731 (N\-1)/N
732 T} T{
733 2/any (see note 2)
734 T}
735 _
736 T{
737 RAID6
738 T} T{
739 1
740 T} T{
741 2
742 T} T{
743 3 to N\-2
744 T} T{
745 (N\-2)/N
746 T} T{
747 3/any (see note 3)
748 T}
749 .TE
750 .sp
751 \fBWARNING:\fP
752 .INDENT 0.0
753 .INDENT 3.5
754 It\(aqs not recommended to create filesystems with RAID0/1/10/5/6
755 profiles on partitions from the same device. Neither redundancy nor
756 performance will be improved.
757 .UNINDENT
758 .UNINDENT
759 .sp
760 \fINote 1:\fP DUP may exist on more than 1 device if it starts on a single device and
761 another one is added. Since version 4.5.1, \fBmkfs.btrfs\fP will let you create DUP
762 on multiple devices without restrictions.
763 .sp
764 \fINote 2:\fP It\(aqs not recommended to use 2 devices with RAID5. In that case,
765 parity stripe will contain the same data as the data stripe, making RAID5
766 degraded to RAID1 with more overhead.
767 .sp
768 \fINote 3:\fP It\(aqs also not recommended to use 3 devices with RAID6, unless you
769 want to get effectively 3 copies in a RAID1\-like manner (but not exactly that).
770 .sp
771 \fINote 4:\fP Since kernel 5.5 it\(aqs possible to use RAID1C3 as replacement for
772 RAID6, higher space cost but reliable.
773 .sp
774 \fINote 5:\fP Since kernel 5.15 it\(aqs possible to use (mount, convert profiles)
775 RAID0 on one device and RAID10 on two devices.
776 .SS PROFILE LAYOUT
777 .sp
778 For the following examples, assume devices numbered by 1, 2, 3 and 4, data or
779 metadata blocks A, B, C, D, with possible stripes e.g. A1, A2 that would be
780 logically A, etc. For parity profiles PA and QA are parity and syndrome,
781 associated with the given stripe. The simple layouts single or DUP are left
782 out. Actual physical block placement on devices depends on current state of
783 the free/allocated space and may appear random. All devices are assumed to be
784 present at the time of the blocks would have been written.
785 .SS RAID1
786 .TS
787 box center;
788 l|l|l|l.
789 T{
790 device 1
791 T} T{
792 device 2
793 T} T{
794 device 3
795 T} T{
796 device 4
797 T}
798 _
799 T{
800 A
801 T} T{
802 D
803 T} T{
804 T} T{
805 T}
806 _
807 T{
808 B
809 T} T{
810 T} T{
811 T} T{
812 C
813 T}
814 _
815 T{
816 C
817 T} T{
818 T} T{
819 T} T{
820 T}
821 _
822 T{
823 D
824 T} T{
825 A
826 T} T{
827 B
828 T} T{
829 T}
830 .TE
831 .SS RAID1C3
832 .TS
833 box center;
834 l|l|l|l.
835 T{
836 device 1
837 T} T{
838 device 2
839 T} T{
840 device 3
841 T} T{
842 device 4
843 T}
844 _
845 T{
846 A
847 T} T{
848 A
849 T} T{
850 D
851 T} T{
852 T}
853 _
854 T{
855 B
856 T} T{
857 T} T{
858 B
859 T} T{
860 T}
861 _
862 T{
863 C
864 T} T{
865 T} T{
866 A
867 T} T{
868 C
869 T}
870 _
871 T{
872 D
873 T} T{
874 D
875 T} T{
876 C
877 T} T{
878 B
879 T}
880 .TE
881 .SS RAID0
882 .TS
883 box center;
884 l|l|l|l.
885 T{
886 device 1
887 T} T{
888 device 2
889 T} T{
890 device 3
891 T} T{
892 device 4
893 T}
894 _
895 T{
896 A2
897 T} T{
898 C3
899 T} T{
900 A3
901 T} T{
902 C2
903 T}
904 _
905 T{
906 B1
907 T} T{
908 A1
909 T} T{
910 D2
911 T} T{
912 B3
913 T}
914 _
915 T{
916 C1
917 T} T{
918 D3
919 T} T{
920 B4
921 T} T{
922 D1
923 T}
924 _
925 T{
926 D4
927 T} T{
928 B2
929 T} T{
930 C4
931 T} T{
932 A4
933 T}
934 .TE
935 .SS RAID5
936 .TS
937 box center;
938 l|l|l|l.
939 T{
940 device 1
941 T} T{
942 device 2
943 T} T{
944 device 3
945 T} T{
946 device 4
947 T}
948 _
949 T{
950 A2
951 T} T{
952 C3
953 T} T{
954 A3
955 T} T{
956 C2
957 T}
958 _
959 T{
960 B1
961 T} T{
962 A1
963 T} T{
964 D2
965 T} T{
966 B3
967 T}
968 _
969 T{
970 C1
971 T} T{
972 D3
973 T} T{
974 PB
975 T} T{
976 D1
977 T}
978 _
979 T{
980 PD
981 T} T{
982 B2
983 T} T{
984 PC
985 T} T{
986 PA
987 T}
988 .TE
989 .SS RAID6
990 .TS
991 box center;
992 l|l|l|l.
993 T{
994 device 1
995 T} T{
996 device 2
997 T} T{
998 device 3
999 T} T{
1000 device 4
1001 T}
1002 _
1003 T{
1004 A2
1005 T} T{
1006 QC
1007 T} T{
1008 QA
1009 T} T{
1010 C2
1011 T}
1012 _
1013 T{
1014 B1
1015 T} T{
1016 A1
1017 T} T{
1018 D2
1019 T} T{
1020 QB
1021 T}
1022 _
1023 T{
1024 C1
1025 T} T{
1026 QD
1027 T} T{
1028 PB
1029 T} T{
1030 D1
1031 T}
1032 _
1033 T{
1034 PD
1035 T} T{
1036 B2
1037 T} T{
1038 PC
1039 T} T{
1040 PA
1041 T}
1042 .TE
1043 .SH DUP PROFILES ON A SINGLE DEVICE
1044 .sp
1045 The mkfs utility will let the user create a filesystem with profiles that write
1046 the logical blocks to 2 physical locations. Whether there are really 2
1047 physical copies highly depends on the underlying device type.
1048 .sp
1049 For example, a SSD drive can remap the blocks internally to a single copy\-\-thus
1050 deduplicating them. This negates the purpose of increased redundancy and just
1051 wastes filesystem space without providing the expected level of redundancy.
1052 .sp
1053 The duplicated data/metadata may still be useful to statistically improve the
1054 chances on a device that might perform some internal optimizations. The actual
1055 details are not usually disclosed by vendors. For example we could expect that
1056 not all blocks get deduplicated. This will provide a non\-zero probability of
1057 recovery compared to a zero chance if the single profile is used. The user
1058 should make the tradeoff decision. The deduplication in SSDs is thought to be
1059 widely available so the reason behind the mkfs default is to not give a false
1060 sense of redundancy.
1061 .sp
1062 As another example, the widely used USB flash or SD cards use a translation
1063 layer between the logical and physical view of the device. The data lifetime
1064 may be affected by frequent plugging. The memory cells could get damaged,
1065 hopefully not destroying both copies of particular data in case of DUP.
1066 .sp
1067 The wear levelling techniques can also lead to reduced redundancy, even if the
1068 device does not do any deduplication. The controllers may put data written in
1069 a short time span into the same physical storage unit (cell, block etc). In case
1070 this unit dies, both copies are lost. BTRFS does not add any artificial delay
1071 between metadata writes.
1072 .sp
1073 The traditional rotational hard drives usually fail at the sector level.
1074 .sp
1075 In any case, a device that starts to misbehave and repairs from the DUP copy
1076 should be replaced! \fBDUP is not backup\fP\&.
1077 .SH KNOWN ISSUES
1078 .sp
1079 \fBSMALL FILESYSTEMS AND LARGE NODESIZE\fP
1080 .sp
1081 The combination of small filesystem size and large nodesize is not recommended
1082 in general and can lead to various ENOSPC\-related issues during mount time or runtime.
1083 .sp
1084 Since mixed block group creation is optional, we allow small
1085 filesystem instances with differing values for \fIsectorsize\fP and \fInodesize\fP
1086 to be created and could end up in the following situation:
1087 .INDENT 0.0
1088 .INDENT 3.5
1089 .sp
1090 .EX
1091 # mkfs.btrfs \-f \-n 65536 /dev/loop0
1092 btrfs\-progs v3.19\-rc2\-405\-g976307c
1093 See https://btrfs.readthedocs.io for more information.
1094
1095 Performing full device TRIM (512.00MiB) ...
1096 Label: (null)
1097 UUID: 49fab72e\-0c8b\-466b\-a3ca\-d1bfe56475f0
1098 Node size: 65536
1099 Sector size: 4096
1100 Filesystem size: 512.00MiB
1101 Block group profiles:
1102 Data: single 8.00MiB
1103 Metadata: DUP 40.00MiB
1104 System: DUP 12.00MiB
1105 SSD detected: no
1106 Incompat features: extref, skinny\-metadata
1107 Number of devices: 1
1108 Devices:
1109 ID SIZE PATH
1110 1 512.00MiB /dev/loop0
1111
1112 # mount /dev/loop0 /mnt/
1113 mount: mount /dev/loop0 on /mnt failed: No space left on device
1114 .EE
1115 .UNINDENT
1116 .UNINDENT
1117 .sp
1118 The ENOSPC occurs during the creation of the UUID tree. This is caused
1119 by large metadata blocks and space reservation strategy that allocates more
1120 than can fit into the filesystem.
1121 .SH AVAILABILITY
1122 .sp
1123 \fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at
1124 \X'tty: link https://btrfs.readthedocs.io'\fI\%https://btrfs.readthedocs.io\fP\X'tty: link'\&.
1125 .SH SEE ALSO
1126 .sp
1127 \fI\%btrfs(5)\fP,
1128 \fI\%btrfs(8)\fP,
1129 \fI\%btrfs\-balance(8)\fP,
1130 \X'tty: link https://man7.org/linux/man-pages/man8/wipefs.8.html'\fI\%wipefs(8)\fP\X'tty: link'
1131 .\" Generated by docutils manpage writer.
1132 .