1BTRFS-MAN5(5) Btrfs Manual BTRFS-MAN5(5)
2
6 btrfs-man5 - topics about the BTRFS filesystem (mount options,
7 supported file attributes and other)
8
10 This document describes topics related to BTRFS that are not specific
11 to the tools. Currently covers:
12 1. mount options
14 2. filesystem features
16 3. checksum algorithms
18 4. filesystem exclusive operations
20 5. filesystem limits
22 6. bootloader support
24 7. file attributes
26 8. control device
28 9. filesystems with multiple block group profiles
30 10. seeding device
32 11. raid56 status and recommended practices
34
36 This section describes mount options specific to BTRFS. For the generic
37 mount options please refer to mount(8) manpage. The options are sorted
38 alphabetically (discarding the no prefix).
39 Note
41 most mount options apply to the whole filesystem and only options
42 in the first mounted subvolume will take effect. This is due to
43 lack of implementation and may change in the future. This means
44 that (for example) you can’t set per-subvolume nodatacow,
45 nodatasum, or compress using mount options. This should eventually
46 be fixed, but it has proved to be difficult to implement correctly
47 within the Linux VFS framework.
48 Mount options are processed in order, only the last occurrence of an
50 option takes effect and may disable other options due to constraints
51 (see eg. nodatacow and compress). The output of mount command shows
52 which options have been applied.
53 acl, noacl
55 (default: on)
56 Enable/disable support for Posix Access Control Lists (ACLs). See
58 the acl(5) manual page for more information about ACLs.
59 The support for ACL is build-time configurable (BTRFS_FS_POSIX_ACL)
61 and mount fails if acl is requested but the feature is not compiled
62 in.
63 autodefrag, noautodefrag
65 (since: 3.0, default: off)
66 Enable automatic file defragmentation. When enabled, small random
68 writes into files (in a range of tens of kilobytes, currently it’s
69 64K) are detected and queued up for the defragmentation process.
70 Not well suited for large database workloads.
71 The read latency may increase due to reading the adjacent blocks
73 that make up the range for defragmentation, successive write will
74 merge the blocks in the new location.
75 Warning
77 Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as
78 well as with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12
79 or ≥ 3.13.4 will break up the reflinks of COW data (for example
80 files copied with cp --reflink, snapshots or de-duplicated
81 data). This may cause considerable increase of space usage
82 depending on the broken up reflinks.
83 barrier, nobarrier
85 (default: on)
86 Ensure that all IO write operations make it through the device
88 cache and are stored permanently when the filesystem is at its
89 consistency checkpoint. This typically means that a flush command
90 is sent to the device that will synchronize all pending data and
91 ordinary metadata blocks, then writes the superblock and issues
92 another flush.
93 The write flushes incur a slight hit and also prevent the IO block
95 scheduler to reorder requests in a more effective way. Disabling
96 barriers gets rid of that penalty but will most certainly lead to a
97 corrupted filesystem in case of a crash or power loss. The ordinary
98 metadata blocks could be yet unwritten at the time the new
99 superblock is stored permanently, expecting that the block pointers
100 to metadata were stored permanently before.
101 On a device with a volatile battery-backed write-back cache, the
103 nobarrier option will not lead to filesystem corruption as the
104 pending blocks are supposed to make it to the permanent storage.
105 check_int, check_int_data, check_int_print_mask=value
107 (since: 3.0, default: off)
108 These debugging options control the behavior of the integrity
110 checking module (the BTRFS_FS_CHECK_INTEGRITY config option
111 required). The main goal is to verify that all blocks from a given
112 transaction period are properly linked.
113 check_int enables the integrity checker module, which examines all
115 block write requests to ensure on-disk consistency, at a large
116 memory and CPU cost.
117 check_int_data includes extent data in the integrity checks, and
119 implies the check_int option.
120 check_int_print_mask takes a bitmask of BTRFSIC_PRINT_MASK_* values
122 as defined in fs/btrfs/check-integrity.c, to control the integrity
123 checker module behavior.
124 See comments at the top of fs/btrfs/check-integrity.c for more
126 information.
127 clear_cache
129 Force clearing and rebuilding of the disk space cache if something
130 has gone wrong. See also: space_cache.
131 commit=seconds
133 (since: 3.12, default: 30)
134 Set the interval of periodic transaction commit when data are
136 synchronized to permanent storage. Higher interval values lead to
137 larger amount of unwritten data, which has obvious consequences
138 when the system crashes. The upper bound is not forced, but a
139 warning is printed if it’s more than 300 seconds (5 minutes). Use
140 with care.
141 compress, compress=type[:level], compress-force,
143 compress-force=type[:level]
144 (default: off, level support since: 5.1)
145 Control BTRFS file data compression. Type may be specified as zlib,
147 lzo, zstd or no (for no compression, used for remounting). If no
148 type is specified, zlib is used. If compress-force is specified,
149 then compression will always be attempted, but the data may end up
150 uncompressed if the compression would make them larger.
151 Both zlib and zstd (since version 5.1) expose the compression level
153 as a tunable knob with higher levels trading speed and memory
154 (zstd) for higher compression ratios. This can be set by appending
155 a colon and the desired level. Zlib accepts the range [1, 9] and
156 zstd accepts [1, 15]. If no level is set, both currently use a
157 default level of 3. The value 0 is an alias for the default level.
158 Otherwise some simple heuristics are applied to detect an
160 incompressible file. If the first blocks written to a file are not
161 compressible, the whole file is permanently marked to skip
162 compression. As this is too simple, the compress-force is a
163 workaround that will compress most of the files at the cost of some
164 wasted CPU cycles on failed attempts. Since kernel 4.15, a set of
165 heuristic algorithms have been improved by using frequency
166 sampling, repeated pattern detection and Shannon entropy
167 calculation to avoid that.
168 Note
170 If compression is enabled, nodatacow and nodatasum are
171 disabled.
172 datacow, nodatacow
174 (default: on)
175 Enable data copy-on-write for newly created files. Nodatacow
177 implies nodatasum, and disables compression. All files created
178 under nodatacow are also set the NOCOW file attribute (see
179 chattr(1)).
180 Note
182 If nodatacow or nodatasum are enabled, compression is disabled.
183 Updates in-place improve performance for workloads that do frequent
184 overwrites, at the cost of potential partial writes, in case the
185 write is interrupted (system crash, device failure).
186 datasum, nodatasum
188 (default: on)
189 Enable data checksumming for newly created files. Datasum implies
191 datacow, ie. the normal mode of operation. All files created under
192 nodatasum inherit the "no checksums" property, however there’s no
193 corresponding file attribute (see chattr(1)).
194 Note
196 If nodatacow or nodatasum are enabled, compression is disabled.
197 There is a slight performance gain when checksums are turned off,
198 the corresponding metadata blocks holding the checksums do not need
199 to updated. The cost of checksumming of the blocks in memory is
200 much lower than the IO, modern CPUs feature hardware support of the
201 checksumming algorithm.
202 degraded
204 (default: off)
205 Allow mounts with less devices than the RAID profile constraints
207 require. A read-write mount (or remount) may fail when there are
208 too many devices missing, for example if a stripe member is
209 completely missing from RAID0.
210 Since 4.14, the constraint checks have been improved and are
212 verified on the chunk level, not an the device level. This allows
213 degraded mounts of filesystems with mixed RAID profiles for data
214 and metadata, even if the device number constraints would not be
215 satisfied for some of the profiles.
216 Example: metadata — raid1, data — single, devices — /dev/sda,
218 /dev/sdb
219 Suppose the data are completely stored on sda, then missing sdb
221 will not prevent the mount, even if 1 missing device would normally
222 prevent (any) single profile to mount. In case some of the data
223 chunks are stored on sdb, then the constraint of single/data is not
224 satisfied and the filesystem cannot be mounted.
225 device=devicepath
227 Specify a path to a device that will be scanned for BTRFS
228 filesystem during mount. This is usually done automatically by a
229 device manager (like udev) or using the btrfs device scan command
230 (eg. run from the initial ramdisk). In cases where this is not
231 possible the device mount option can help.
232 Note
234 booting eg. a RAID1 system may fail even if all filesystem’s
235 device paths are provided as the actual device nodes may not be
236 discovered by the system at that point.
237 discard, discard=sync, discard=async, nodiscard
239 (default: off, async support since: 5.6)
240 Enable discarding of freed file blocks. This is useful for SSD
242 devices, thinly provisioned LUNs, or virtual machine images;
243 however, every storage layer must support discard for it to work.
244 In the synchronous mode (sync or without option value), lack of
246 asynchronous queued TRIM on the backing device TRIM can severely
247 degrade performance, because a synchronous TRIM operation will be
248 attempted instead. Queued TRIM requires newer than SATA revision
249 3.1 chipsets and devices.
250 The asynchronous mode (async) gathers extents in larger chunks
252 before sending them to the devices for TRIM. The overhead and
253 performance impact should be negligible compared to the previous
254 mode and it’s supposed to be the preferred mode if needed.
255 If it is not necessary to immediately discard freed blocks, then
257 the fstrim tool can be used to discard all free blocks in a batch.
258 Scheduling a TRIM during a period of low system activity will
259 prevent latent interference with the performance of other
260 operations. Also, a device may ignore the TRIM command if the range
261 is too small, so running a batch discard has a greater probability
262 of actually discarding the blocks.
263 enospc_debug, noenospc_debug
265 (default: off)
266 Enable verbose output for some ENOSPC conditions. It’s safe to use
268 but can be noisy if the system reaches near-full state.
269 fatal_errors=action
271 (since: 3.4, default: bug)
272 Action to take when encountering a fatal error.
274 bug
276 BUG() on a fatal error, the system will stay in the crashed
277 state and may be still partially usable, but reboot is required
278 for full operation
279 panic
281 panic() on a fatal error, depending on other system
282 configuration, this may be followed by a reboot. Please refer
283 to the documentation of kernel boot parameters, eg. panic,
284 oops or crashkernel.
285 flushoncommit, noflushoncommit
287 (default: off)
288 This option forces any data dirtied by a write in a prior
290 transaction to commit as part of the current commit, effectively a
291 full filesystem sync.
292 This makes the committed state a fully consistent view of the file
294 system from the application’s perspective (i.e. it includes all
295 completed file system operations). This was previously the behavior
296 only when a snapshot was created.
297 When off, the filesystem is consistent but buffered writes may last
299 more than one transaction commit.
300 fragment=type
302 (depends on compile-time option BTRFS_DEBUG, since: 4.4, default:
303 off)
304 A debugging helper to intentionally fragment given type of block
306 groups. The type can be data, metadata or all. This mount option
307 should not be used outside of debugging environments and is not
308 recognized if the kernel config option BTRFS_DEBUG is not enabled.
309 nologreplay
311 (default: off, even read-only)
312 The tree-log contains pending updates to the filesystem until the
314 full commit. The log is replayed on next mount, this can be
315 disabled by this option. See also treelog. Note that nologreplay is
316 the same as norecovery.
317 Warning
319 currently, the tree log is replayed even with a read-only
320 mount! To disable that behaviour, mount also with nologreplay.
321 max_inline=bytes
323 (default: min(2048, page size) )
324 Specify the maximum amount of space, that can be inlined in a
326 metadata B-tree leaf. The value is specified in bytes, optionally
327 with a K suffix (case insensitive). In practice, this value is
328 limited by the filesystem block size (named sectorsize at mkfs
329 time), and memory page size of the system. In case of sectorsize
330 limit, there’s some space unavailable due to leaf headers. For
331 example, a 4k sectorsize, maximum size of inline data is about 3900
332 bytes.
333 Inlining can be completely turned off by specifying 0. This will
335 increase data block slack if file sizes are much smaller than block
336 size but will reduce metadata consumption in return.
337 Note
339 the default value has changed to 2048 in kernel 4.6.
340 metadata_ratio=value
342 (default: 0, internal logic)
343 Specifies that 1 metadata chunk should be allocated after every
345 value data chunks. Default behaviour depends on internal logic,
346 some percent of unused metadata space is attempted to be maintained
347 but is not always possible if there’s not enough space left for
348 chunk allocation. The option could be useful to override the
349 internal logic in favor of the metadata allocation if the expected
350 workload is supposed to be metadata intense (snapshots, reflinks,
351 xattrs, inlined files).
352 norecovery
354 (since: 4.5, default: off)
355 Do not attempt any data recovery at mount time. This will disable
357 logreplay and avoids other write operations. Note that this option
358 is the same as nologreplay.
359 Note
361 The opposite option recovery used to have different meaning but
362 was changed for consistency with other filesystems, where
363 norecovery is used for skipping log replay. BTRFS does the same
364 and in general will try to avoid any write operations.
365 rescan_uuid_tree
367 (since: 3.12, default: off)
368 Force check and rebuild procedure of the UUID tree. This should not
370 normally be needed.
371 rescue
373 (since: 5.9)
374 Modes allowing mount with damaged filesystem structures.
376 • usebackuproot (since: 5.9, replaces standalone option
378 usebackuproot)
379 • nologreplay (since: 5.9, replaces standalone option
381 nologreplay)
382 • ignorebadroots, ibadroots (since: 5.11)
384 • ignoredatacsums, idatacsums (since: 5.11)
386 • all (since: 5.9)
388 skip_balance
390 (since: 3.3, default: off)
391 Skip automatic resume of an interrupted balance operation. The
393 operation can later be resumed with btrfs balance resume, or the
394 paused state can be removed with btrfs balance cancel. The default
395 behaviour is to resume an interrupted balance immediately after a
396 volume is mounted.
397 space_cache, space_cache=version, nospace_cache
399 (nospace_cache since: 3.2, space_cache=v1 and space_cache=v2 since
400 4.5, default: space_cache=v1)
401 Options to control the free space cache. The free space cache
403 greatly improves performance when reading block group free space
404 into memory. However, managing the space cache consumes some
405 resources, including a small amount of disk space.
406 There are two implementations of the free space cache. The original
408 one, referred to as v1, is the safe default. The v1 space cache can
409 be disabled at mount time with nospace_cache without clearing.
410 On very large filesystems (many terabytes) and certain workloads,
412 the performance of the v1 space cache may degrade drastically. The
413 v2 implementation, which adds a new B-tree called the free space
414 tree, addresses this issue. Once enabled, the v2 space cache will
415 always be used and cannot be disabled unless it is cleared. Use
416 clear_cache,space_cache=v1 or clear_cache,nospace_cache to do so.
417 If v2 is enabled, kernels without v2 support will only be able to
418 mount the filesystem in read-only mode. The btrfs(8) command
419 currently only has read-only support for v2. A read-write command
420 may be run on a v2 filesystem by clearing the cache, running the
421 command, and then remounting with space_cache=v2.
422 If a version is not explicitly specified, the default
424 implementation will be chosen, which is v1.
425 ssd, ssd_spread, nossd, nossd_spread
427 (default: SSD autodetected)
428 Options to control SSD allocation schemes. By default, BTRFS will
430 enable or disable SSD optimizations depending on status of a device
431 with respect to rotational or non-rotational type. This is
432 determined by the contents of /sys/block/DEV/queue/rotational). If
433 it is 0, the ssd option is turned on. The option nossd will disable
434 the autodetection.
435 The optimizations make use of the absence of the seek penalty
437 that’s inherent for the rotational devices. The blocks can be
438 typically written faster and are not offloaded to separate threads.
439 Note
441 Since 4.14, the block layout optimizations have been dropped.
442 This used to help with first generations of SSD devices. Their
443 FTL (flash translation layer) was not effective and the
444 optimization was supposed to improve the wear by better
445 aligning blocks. This is no longer true with modern SSD devices
446 and the optimization had no real benefit. Furthermore it caused
447 increased fragmentation. The layout tuning has been kept intact
448 for the option ssd_spread.
449 The ssd_spread mount option attempts to allocate into bigger and
450 aligned chunks of unused space, and may perform better on low-end
451 SSDs. ssd_spread implies ssd, enabling all other SSD heuristics as
452 well. The option nossd will disable all SSD options while
453 nossd_spread only disables ssd_spread.
454 subvol=path
456 Mount subvolume from path rather than the toplevel subvolume. The
457 path is always treated as relative to the toplevel subvolume. This
458 mount option overrides the default subvolume set for the given
459 filesystem.
460 subvolid=subvolid
462 Mount subvolume specified by a subvolid number rather than the
463 toplevel subvolume. You can use btrfs subvolume list of btrfs
464 subvolume show to see subvolume ID numbers. This mount option
465 overrides the default subvolume set for the given filesystem.
466 Note
468 if both subvolid and subvol are specified, they must point at
469 the same subvolume, otherwise the mount will fail.
470 thread_pool=number
472 (default: min(NRCPUS + 2, 8) )
473 The number of worker threads to start. NRCPUS is number of on-line
475 CPUs detected at the time of mount. Small number leads to less
476 parallelism in processing data and metadata, higher numbers could
477 lead to a performance hit due to increased locking contention,
478 process scheduling, cache-line bouncing or costly data transfers
479 between local CPU memories.
480 treelog, notreelog
482 (default: on)
483 Enable the tree logging used for fsync and O_SYNC writes. The tree
485 log stores changes without the need of a full filesystem sync. The
486 log operations are flushed at sync and transaction commit. If the
487 system crashes between two such syncs, the pending tree log
488 operations are replayed during mount.
489 Warning
491 currently, the tree log is replayed even with a read-only
492 mount! To disable that behaviour, also mount with nologreplay.
493 The tree log could contain new files/directories, these would not
494 exist on a mounted filesystem if the log is not replayed.
495 usebackuproot
497 (since: 4.6, default: off)
498 Enable autorecovery attempts if a bad tree root is found at mount
500 time. Currently this scans a backup list of several previous tree
501 roots and tries to use the first readable. This can be used with
502 read-only mounts as well.
503 Note
505 This option has replaced recovery.
506 user_subvol_rm_allowed
508 (default: off)
509 Allow subvolumes to be deleted by their respective owner.
511 Otherwise, only the root user can do that.
512 Note
514 historically, any user could create a snapshot even if he was
515 not owner of the source subvolume, the subvolume deletion has
516 been restricted for that reason. The subvolume creation has
517 been restricted but this mount option is still required. This
518 is a usability issue. Since 4.18, the rmdir(2) syscall can
519 delete an empty subvolume just like an ordinary directory.
520 Whether this is possible can be detected at runtime, see
521 rmdir_subvol feature in FILESYSTEM FEATURES.
522 DEPRECATED MOUNT OPTIONS
524 List of mount options that have been removed, kept for backward
525 compatibility.
526 recovery
528 (since: 3.2, default: off, deprecated since: 4.5)
529 Note
531 this option has been replaced by usebackuproot and should not
532 be used but will work on 4.5+ kernels.
533 inode_cache, noinode_cache
535 (removed in: 5.11, since: 3.0, default: off)
536 Note
538 the functionality has been removed in 5.11, any stale data
539 created by previous use of the inode_cache option can be
540 removed by btrfs check --clear-ino-cache.
541 NOTES ON GENERIC MOUNT OPTIONS
543 Some of the general mount options from mount(8) that affect BTRFS and
544 are worth mentioning.
545 noatime
547 under read intensive work-loads, specifying noatime significantly
548 improves performance because no new access time information needs
549 to be written. Without this option, the default is relatime, which
550 only reduces the number of inode atime updates in comparison to the
551 traditional strictatime. The worst case for atime updates under
552 relatime occurs when many files are read whose atime is older than
553 24 h and which are freshly snapshotted. In that case the atime is
554 updated and COW happens - for each file - in bulk. See also
555 https://lwn.net/Articles/499293/ - Atime and btrfs: a bad
556 combination? (LWN, 2012-05-31).
557 Note that noatime may break applications that rely on atime uptimes
559 like the venerable Mutt (unless you use maildir mailboxes).
560
562 The basic set of filesystem features gets extended over time. The
563 backward compatibility is maintained and the features are optional,
564 need to be explicitly asked for so accidental use will not create
565 incompatibilities.
566 There are several classes and the respective tools to manage the
568 features:
569 at mkfs time only
571 This is namely for core structures, like the b-tree nodesize or
572 checksum algorithm, see mkfs.btrfs(8) for more details.
573 after mkfs, on an unmounted filesystem
575 Features that may optimize internal structures or add new
576 structures to support new functionality, see btrfstune(8). The
577 command btrfs inspect-internal dump-super device will dump a
578 superblock, you can map the value of incompat_flags to the features
579 listed below
580 after mkfs, on a mounted filesystem
582 The features of a filesystem (with a given UUID) are listed in
583 /sys/fs/btrfs/UUID/features/, one file per feature. The status is
584 stored inside the file. The value 1 is for enabled and active,
585 while 0 means the feature was enabled at mount time but turned off
586 afterwards.
587 Whether a particular feature can be turned on a mounted filesystem
589 can be found in the directory /sys/fs/btrfs/features/, one file per
590 feature. The value 1 means the feature can be enabled.
591 List of features (see also mkfs.btrfs(8) section FILESYSTEM FEATURES):
593 big_metadata
595 (since: 3.4)
596 the filesystem uses nodesize for metadata blocks, this can be
598 bigger than the page size
599 compress_lzo
601 (since: 2.6.38)
602 the lzo compression has been used on the filesystem, either as a
604 mount option or via btrfs filesystem defrag.
605 compress_zstd
607 (since: 4.14)
608 the zstd compression has been used on the filesystem, either as a
610 mount option or via btrfs filesystem defrag.
611 default_subvol
613 (since: 2.6.34)
614 the default subvolume has been set on the filesystem
616 extended_iref
618 (since: 3.7)
619 increased hardlink limit per file in a directory to 65536, older
621 kernels supported a varying number of hardlinks depending on the
622 sum of all file name sizes that can be stored into one metadata
623 block
624 free_space_tree
626 (since: 4.5)
627 free space representation using a dedicated b-tree, successor of v1
629 space cache
630 metadata_uuid
632 (since: 5.0)
633 the main filesystem UUID is the metadata_uuid, which stores the new
635 UUID only in the superblock while all metadata blocks still have
636 the UUID set at mkfs time, see btrfstune(8) for more
637 mixed_backref
639 (since: 2.6.31)
640 the last major disk format change, improved backreferences, now
642 default
643 mixed_groups
645 (since: 2.6.37)
646 mixed data and metadata block groups, ie. the data and metadata are
648 not separated and occupy the same block groups, this mode is
649 suitable for small volumes as there are no constraints how the
650 remaining space should be used (compared to the split mode, where
651 empty metadata space cannot be used for data and vice versa)
652 on the other hand, the final layout is quite unpredictable and
654 possibly highly fragmented, which means worse performance
655 no_holes
657 (since: 3.14)
658 improved representation of file extents where holes are not
660 explicitly stored as an extent, saves a few percent of metadata if
661 sparse files are used
662 raid1c34
664 (since: 5.5)
665 extended RAID1 mode with copies on 3 or 4 devices respectively
667 raid56
669 (since: 3.9)
670 the filesystem contains or contained a raid56 profile of block
672 groups
673 rmdir_subvol
675 (since: 4.18)
676 indicate that rmdir(2) syscall can delete an empty subvolume just
678 like an ordinary directory. Note that this feature only depends on
679 the kernel version.
680 skinny_metadata
682 (since: 3.10)
683 reduced-size metadata for extent references, saves a few percent of
685 metadata
686 send_stream_version
688 (since: 5.10)
689 number of the highest supported send stream version
691 supported_checksums
693 (since: 5.5)
694 list of checksum algorithms supported by the kernel module, the
696 respective modules or built-in implementing the algorithms need to
697 be present to mount the filesystem, see CHECKSUM ALGORITHMS
698 supported_sectorsizes
700 (since: 5.13)
701 list of values that are accepted as sector sizes (mkfs.btrfs
703 --sectorsize) by the running kernel
704 supported_rescue_options
706 (since: 5.11)
707 list of values for the mount option rescue that are supported by
709 the running kernel, see btrfs(5)
710 zoned
712 (since: 5.12)
713 zoned mode is allocation/write friendly to host-managed devices,
715 allocation space is split into fixed-size zones that must be
716 updated sequentially
717 SWAPFILE SUPPORT
719 The swapfile is supported since kernel 5.0. Use swapon(8) to activate
720 the swapfile. There are some limitations of the implementation in btrfs
721 and linux swap subsystem:
722 • filesystem - must be only single device
724 • filesystem - must have only single data profile
726 • swapfile - the containing subvolume cannot be snapshotted
728 • swapfile - must be preallocated
730 • swapfile - must be nodatacow (ie. also nodatasum)
732 • swapfile - must not be compressed
734 The limitations come namely from the COW-based design and mapping layer
736 of blocks that allows the advanced features like relocation and
737 multi-device filesystems. However, the swap subsystem expects simpler
738 mapping and no background changes of the file blocks once they’ve been
739 attached to swap.
740 With active swapfiles, the following whole-filesystem operations will
742 skip swapfile extents or may fail:
743 • balance - block groups with swapfile extents are skipped and
745 reported, the rest will be processed normally
746 • resize grow - unaffected
748 • resize shrink - works as long as the extents are outside of the
750 shrunk range
751 • device add - a new device does not interfere with existing swapfile
753 and this operation will work, though no new swapfile can be
754 activated afterwards
755 • device delete - if the device has been added as above, it can be
757 also deleted
758 • device replace - ditto
760 When there are no active swapfiles and a whole-filesystem exclusive
762 operation is running (ie. balance, device delete, shrink), the
763 swapfiles cannot be temporarily activated. The operation must finish
764 first.
765 To create and activate a swapfile run the following commands:
767 # truncate -s 0 swapfile
769 # chattr +C swapfile
770 # fallocate -l 2G swapfile
771 # chmod 0600 swapfile
772 # mkswap swapfile
773 # swapon swapfile
774 Please note that the UUID returned by the mkswap utility identifies the
776 swap "filesystem" and because it’s stored in a file, it’s not generally
777 visible and usable as an identifier unlike if it was on a block device.
778 The file will appear in /proc/swaps:
780 # cat /proc/swaps
782 Filename Type Size Used Priority
783 /path/swapfile file 2097152 0 -2
784 The swapfile can be created as one-time operation or, once properly
786 created, activated on each boot by the swapon -a command (usually
787 started by the service manager). Add the following entry to /etc/fstab,
788 assuming the filesystem that provides the /path has been already
789 mounted at this point. Additional mount options relevant for the
790 swapfile can be set too (like priority, not the btrfs mount options).
791 /path/swapfile none swap defaults 0 0
793
795 There are several checksum algorithms supported. The default and
796 backward compatible is crc32c. Since kernel 5.5 there are three more
797 with different characteristics and trade-offs regarding speed and
798 strength. The following list may help you to decide which one to
799 select.
800 CRC32C (32bit digest)
802 default, best backward compatibility, very fast, modern CPUs have
803 instruction-level support, not collision-resistant but still good
804 error detection capabilities
805 XXHASH (64bit digest)
807 can be used as CRC32C successor, very fast, optimized for modern
808 CPUs utilizing instruction pipelining, good collision resistance
809 and error detection
810 SHA256 (256bit digest)
812 a cryptographic-strength hash, relatively slow but with possible
813 CPU instruction acceleration or specialized hardware cards, FIPS
814 certified and in wide use
815 BLAKE2b (256bit digest)
817 a cryptographic-strength hash, relatively fast with possible CPU
818 acceleration using SIMD extensions, not standardized but based on
819 BLAKE which was a SHA3 finalist, in wide use, the algorithm used is
820 BLAKE2b-256 that’s optimized for 64bit platforms
821 The digest size affects overall size of data block checksums stored in
823 the filesystem. The metadata blocks have a fixed area up to 256bits (32
824 bytes), so there’s no increase. Each data block has a separate checksum
825 stored, with additional overhead of the b-tree leaves.
826 Approximate relative performance of the algorithms, measured against
828 CRC32C using reference software implementations on a 3.5GHz intel CPU:
829 ┌────────┬─────────────┬───────┐
831 │ │ │ │
832 │Digest │ Cycles/4KiB │ Ratio │
833 ├────────┼─────────────┼───────┤
834 │ │ │ │
835 │CRC32C │ 1700 │ 1.00 │
836 ├────────┼─────────────┼───────┤
837 │ │ │ │
838 │XXHASH │ 2500 │ 1.44 │
839 ├────────┼─────────────┼───────┤
840 │ │ │ │
841 │SHA256 │ 105000 │ 61 │
842 ├────────┼─────────────┼───────┤
843 │ │ │ │
844 │BLAKE2b │ 22000 │ 13 │
845 └────────┴─────────────┴───────┘
846
848 There are several operations that affect the whole filesystem and
849 cannot be run in parallel. Attempt to start one while another is
850 running will fail.
851 Since kernel 5.10 the currently running operation can be obtained from
853 /sys/fs/UUID/exclusive_operation with following values and operations:
854 • balance
856 • device add
858 • device delete
860 • device replace
862 • resize
864 • swapfile activate
866 • none
868 Enqueuing is supported for several btrfs subcommands so they can be
870 started at once and then serialized.
871
873 maximum file name length
874 255
875 maximum symlink target length
877 depends on the nodesize value, for 4k it’s 3949 bytes, for larger
878 nodesize it’s 4095 due to the system limit PATH_MAX
879 The symlink target may not be a valid path, ie. the path name
881 components can exceed the limits (NAME_MAX), there’s no content
882 validation at symlink(3) creation.
883 maximum number of inodes
885 2^64 but depends on the available metadata space as the inodes are
886 created dynamically
887 inode numbers
889 minimum number: 256 (for subvolumes), regular files and
890 directories: 257
891 maximum file length
893 inherent limit of btrfs is 2^64 (16 EiB) but the linux VFS limit is
894 2^63 (8 EiB)
895 maximum number of subvolumes
897 the subvolume ids can go up to 2^64 but the number of actual
898 subvolumes depends on the available metadata space, the space
899 consumed by all subvolume metadata includes bookkeeping of shared
900 extents can be large (MiB, GiB)
901 maximum number of hardlinks of a file in a directory
903 65536 when the extref feature is turned on during mkfs (default),
904 roughly 100 otherwise
905 minimum filesystem size
907 the minimal size of each device depends on the mixed-bg feature,
908 without that (the default) it’s about 109MiB, with mixed-bg it’s is
909 16MiB
910
912 GRUB2 (https://www.gnu.org/software/grub) has the most advanced support
913 of booting from BTRFS with respect to features.
914 U-boot (https://www.denx.de/wiki/U-Boot/) has decent support for
916 booting but not all BTRFS features are implemented, check the
917 documentation.
918 EXTLINUX (from the https://syslinux.org project) can boot but does not
920 support all features. Please check the upstream documentation before
921 you use it.
922 The first 1MiB on each device is unused with the exception of primary
924 superblock that is on the offset 64KiB and spans 4KiB.
925
927 The btrfs filesystem supports setting file attributes or flags. Note
928 there are old and new interfaces, with confusing names. The following
929 list should clarify that:
930 • attributes: chattr(1) or lsattr(1) utilities (the ioctls are
932 FS_IOC_GETFLAGS and FS_IOC_SETFLAGS), due to the ioctl names the
933 attributes are also called flags
934 • xflags: to distinguish from the previous, it’s extended flags, with
936 tunable bits similar to the attributes but extensible and new bits
937 will be added in the future (the ioctls are FS_IOC_FSGETXATTR and
938 FS_IOC_FSSETXATTR but they are not related to extended attributes
939 that are also called xattrs), there’s no standard tool to change
940 the bits, there’s support in xfs_io(8) as command xfs_io -c chattr
941 ATTRIBUTES
943 a
944 append only, new writes are always written at the end of the file
945 A
947 no atime updates
948 c
950 compress data, all data written after this attribute is set will be
951 compressed. Please note that compression is also affected by the
952 mount options or the parent directory attributes.
953 When set on a directory, all newly created files will inherit this
955 attribute. This attribute cannot be set with m at the same time.
956 C
958 no copy-on-write, file data modifications are done in-place
959 When set on a directory, all newly created files will inherit this
961 attribute.
962 Note
964 due to implementation limitations, this flag can be set/unset
965 only on empty files.
966 d
968 no dump, makes sense with 3rd party tools like dump(8), on BTRFS
969 the attribute can be set/unset but no other special handling is
970 done
971 D
973 synchronous directory updates, for more details search open(2) for
974 O_SYNC and O_DSYNC
975 i
977 immutable, no file data and metadata changes allowed even to the
978 root user as long as this attribute is set (obviously the exception
979 is unsetting the attribute)
980 m
982 no compression, permanently turn off compression on the given file.
983 Any compression mount options will not affect this file. (chattr
984 support added in 1.46.2)
985 When set on a directory, all newly created files will inherit this
987 attribute. This attribute cannot be set with c at the same time.
988 S
990 synchronous updates, for more details search open(2) for O_SYNC and
991 O_DSYNC
992 No other attributes are supported. For the complete list please refer
994 to the chattr(1) manual page.
995 XFLAGS
997 There’s overlap of letters assigned to the bits with the attributes,
998 this list refers to what xfs_io(8) provides:
999 i
1001 immutable, same as the attribute
1002 a
1004 append only, same as the attribute
1005 s
1007 synchronous updates, same as the attribute S
1008 A
1010 no atime updates, same as the attribute
1011 d
1013 no dump, same as the attribute
1014
1016 There’s a character special device /dev/btrfs-control with major and
1017 minor numbers 10 and 234 (the device can be found under the misc
1018 category).
1019 $ ls -l /dev/btrfs-control
1021 crw------- 1 root root 10, 234 Jan 1 12:00 /dev/btrfs-control
1022 The device accepts some ioctl calls that can perform following actions
1024 on the filesystem module:
1025 • scan devices for btrfs filesystem (ie. to let multi-device
1027 filesystems mount automatically) and register them with the kernel
1028 module
1029 • similar to scan, but also wait until the device scanning process is
1031 finished for a given filesystem
1032 • get the supported features (can be also found under
1034 /sys/fs/btrfs/features)
1035 The device is created when btrfs is initialized, either as a module or
1037 a built-in functionality and makes sense only in connection with that.
1038 Running eg. mkfs without the module loaded will not register the device
1039 and will probably warn about that.
1040 In rare cases when the module is loaded but the device is not present
1042 (most likely accidentally deleted), it’s possible to recreate it by
1043 # mknod --mode=600 /dev/btrfs-control c 10 234
1045 or (since 5.11) by a convenience command
1047 # btrfs rescue create-control-device
1049 The control device is not strictly required but the device scanning
1051 will not work and a workaround would need to be used to mount a
1052 multi-device filesystem. The mount option device can trigger the device
1053 scanning during mount, see also btrfs device scan.
1054
1056 It is possible that a btrfs filesystem contains multiple block group
1057 profiles of the same type. This could happen when a profile conversion
1058 using balance filters is interrupted (see btrfs-balance(8)). Some btrfs
1059 commands perform a test to detect this kind of condition and print a
1060 warning like this:
1061 WARNING: Multiple block group profiles detected, see 'man btrfs(5)'.
1063 WARNING: Data: single, raid1
1064 WARNING: Metadata: single, raid1
1065 The corresponding output of btrfs filesystem df might look like:
1067 WARNING: Multiple block group profiles detected, see 'man btrfs(5)'.
1069 WARNING: Data: single, raid1
1070 WARNING: Metadata: single, raid1
1071 Data, RAID1: total=832.00MiB, used=0.00B
1072 Data, single: total=1.63GiB, used=0.00B
1073 System, single: total=4.00MiB, used=16.00KiB
1074 Metadata, single: total=8.00MiB, used=112.00KiB
1075 Metadata, RAID1: total=64.00MiB, used=32.00KiB
1076 GlobalReserve, single: total=16.25MiB, used=0.00B
1077 There’s more than one line for type Data and Metadata, while the
1079 profiles are single and RAID1.
1080 This state of the filesystem OK but most likely needs the
1082 user/administrator to take an action and finish the interrupted tasks.
1083 This cannot be easily done automatically, also the user knows the
1084 expected final profiles.
1085 In the example above, the filesystem started as a single device and
1087 single block group profile. Then another device was added, followed by
1088 balance with convert=raid1 but for some reason hasn’t finished.
1089 Restarting the balance with convert=raid1 will continue and end up with
1090 filesystem with all block group profiles RAID1.
1091 Note
1093 If you’re familiar with balance filters, you can use
1094 convert=raid1,profiles=single,soft, which will take only the
1095 unconverted single profiles and convert them to raid1. This may
1096 speed up the conversion as it would not try to rewrite the already
1097 convert raid1 profiles.
1098 Having just one profile is desired as this also clearly defines the
1100 profile of newly allocated block groups, otherwise this depends on
1101 internal allocation policy. When there are multiple profiles present,
1102 the order of selection is RAID6, RAID5, RAID10, RAID1, RAID0 as long as
1103 the device number constraints are satisfied.
1104 Commands that print the warning were chosen so they’re brought to user
1106 attention when the filesystem state is being changed in that regard.
1107 This is: device add, device delete, balance cancel, balance pause.
1108 Commands that report space usage: filesystem df, device usage. The
1109 command filesystem usage provides a line in the overall summary:
1110 Multiple profiles: yes (data, metadata)
1112
1114 The COW mechanism and multiple devices under one hood enable an
1115 interesting concept, called a seeding device: extending a read-only
1116 filesystem on a single device filesystem with another device that
1117 captures all writes. For example imagine an immutable golden image of
1118 an operating system enhanced with another device that allows to use the
1119 data from the golden image and normal operation. This idea originated
1120 on CD-ROMs with base OS and allowing to use them for live systems, but
1121 this became obsolete. There are technologies providing similar
1122 functionality, like unionmount, overlayfs or qcow2 image snapshot.
1123 The seeding device starts as a normal filesystem, once the contents is
1125 ready, btrfstune -S 1 is used to flag it as a seeding device. Mounting
1126 such device will not allow any writes, except adding a new device by
1127 btrfs device add. Then the filesystem can be remounted as read-write.
1128 Given that the filesystem on the seeding device is always recognized as
1130 read-only, it can be used to seed multiple filesystems, at the same
1131 time. The UUID that is normally attached to a device is automatically
1132 changed to a random UUID on each mount.
1133 Once the seeding device is mounted, it needs the writable device. After
1135 adding it, something like remount -o remount,rw /path makes the
1136 filesystem at /path ready for use. The simplest usecase is to throw
1137 away all changes by unmounting the filesystem when convenient.
1138 Alternatively, deleting the seeding device from the filesystem can turn
1140 it into a normal filesystem, provided that the writable device can also
1141 contain all the data from the seeding device.
1142 The seeding device flag can be cleared again by btrfstune -f -s 0, eg.
1144 allowing to update with newer data but please note that this will
1145 invalidate all existing filesystems that use this particular seeding
1146 device. This works for some usecases, not for others, and a forcing
1147 flag to the command is mandatory to avoid accidental mistakes.
1148 Example how to create and use one seeding device:
1150 # mkfs.btrfs /dev/sda
1152 # mount /dev/sda /mnt/mnt1
1153 # ... fill mnt1 with data
1154 # umount /mnt/mnt1
1155 # btrfstune -S 1 /dev/sda
1156 # mount /dev/sda /mnt/mnt1
1157 # btrfs device add /dev/sdb /mnt
1158 # mount -o remount,rw /mnt/mnt1
1159 # ... /mnt/mnt1 is now writable
1160 Now /mnt/mnt1 can be used normally. The device /dev/sda can be mounted
1162 again with a another writable device:
1163 # mount /dev/sda /mnt/mnt2
1165 # btrfs device add /dev/sdc /mnt/mnt2
1166 # mount -o remount,rw /mnt/mnt2
1167 # ... /mnt/mnt2 is now writable
1168 The writable device (/dev/sdb) can be decoupled from the seeding device
1170 and used independently:
1171 # btrfs device delete /dev/sda /mnt/mnt1
1173 As the contents originated in the seeding device, it’s possible to turn
1175 /dev/sdb to a seeding device again and repeat the whole process.
1176 A few things to note:
1178 • it’s recommended to use only single device for the seeding device,
1180 it works for multiple devices but the single profile must be used
1181 in order to make the seeding device deletion work
1182 • block group profiles single and dup support the usecases above
1184 • the label is copied from the seeding device and can be changed by
1186 btrfs filesystem label
1187 • each new mount of the seeding device gets a new random UUID
1189
1191 The RAID56 feature provides striping and parity over several devices,
1192 same as the traditional RAID5/6. There are some implementation and
1193 design deficiencies that make it unreliable for some corner cases and
1194 the feature should not be used in production, only for evaluation or
1195 testing. The power failure safety for metadata with RAID56 is not 100%.
1196 Metadata
1198 Do not use raid5 nor raid6 for metadata. Use raid1 or raid1c3
1199 respectively.
1200 The substitute profiles provide the same guarantees against loss of 1
1202 or 2 devices, and in some respect can be an improvement. Recovering
1203 from one missing device will only need to access the remaining 1st or
1204 2nd copy, that in general may be stored on some other devices due to
1205 the way RAID1 works on btrfs, unlike on a striped profile (similar to
1206 raid0) that would need all devices all the time.
1207 The space allocation pattern and consumption is different (eg. on N
1209 devices): for raid5 as an example, a 1GiB chunk is reserved on each
1210 device, while with raid1 there’s each 1GiB chunk stored on 2 devices.
1211 The consumption of each 1GiB of used metadata is then N * 1GiB for vs 2
1212 * 1GiB. Using raid1 is also more convenient for balancing/converting to
1213 other profile due to lower requirement on the available chunk space.
1214 Missing/incomplete support
1216 When RAID56 is on the same filesystem with different raid profiles, the
1217 space reporting is inaccurate, eg. df, btrfs filesystem df or btrfs
1218 filesystem usge. When there’s only a one profile per block group type
1219 (eg. raid5 for data) the reporting is accurate.
1220 When scrub is started on a RAID56 filesystem, it’s started on all
1222 devices that degrade the performance. The workaround is to start it on
1223 each device separately. Due to that the device stats may not match the
1224 actual state and some errors might get reported multiple times.
1225 The write hole problem.
1227
1229 acl(5), btrfs(8), chattr(1), fstrim(8), ioctl(2), mkfs.btrfs(8),
1230 mount(8), swapon(8)
1231Btrfs v5.12.1 05/13/2021 BTRFS-MAN5(5)