Debian Codegraph @

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

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