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. filesystem limits
18 4. bootloader support
20 5. file attributes
22 6. control device
24
26 This section describes mount options specific to BTRFS. For the generic
27 mount options please refer to mount(8) manpage. The options are sorted
28 alphabetically (discarding the no prefix).
29 Note
31 most mount options apply to the whole filesystem and only options
32 in the first mounted subvolume will take effect. This is due to
33 lack of implementation and may change in the future. This means
34 that (for example) you can’t set per-subvolume nodatacow,
35 nodatasum, or compress using mount options. This should eventually
36 be fixed, but it has proved to be difficult to implement correctly
37 within the Linux VFS framework.
38 acl, noacl
40 (default: on)
41 Enable/disable support for Posix Access Control Lists (ACLs). See
43 the acl(5) manual page for more information about ACLs.
44 The support for ACL is build-time configurable (BTRFS_FS_POSIX_ACL)
46 and mount fails if acl is requested but the feature is not compiled
47 in.
48 autodefrag, noautodefrag
50 (since: 3.0, default: off)
51 Enable automatic file defragmentation. When enabled, small random
53 writes into files (in a range of tens of kilobytes, currently it’s
54 64K) are detected and queued up for the defragmentation process.
55 Not well suited for large database workloads.
56 The read latency may increase due to reading the adjacent blocks
58 that make up the range for defragmentation, successive write will
59 merge the blocks in the new location.
60 Warning
62 Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as
63 well as with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12
64 or ≥ 3.13.4 will break up the reflinks of COW data (for example
65 files copied with cp --reflink, snapshots or de-duplicated
66 data). This may cause considerable increase of space usage
67 depending on the broken up reflinks.
68 barrier, nobarrier
70 (default: on)
71 Ensure that all IO write operations make it through the device
73 cache and are stored permanently when the filesystem is at its
74 consistency checkpoint. This typically means that a flush command
75 is sent to the device that will synchronize all pending data and
76 ordinary metadata blocks, then writes the superblock and issues
77 another flush.
78 The write flushes incur a slight hit and also prevent the IO block
80 scheduler to reorder requests in a more effective way. Disabling
81 barriers gets rid of that penalty but will most certainly lead to a
82 corrupted filesystem in case of a crash or power loss. The ordinary
83 metadata blocks could be yet unwritten at the time the new
84 superblock is stored permanently, expecting that the block pointers
85 to metadata were stored permanently before.
86 On a device with a volatile battery-backed write-back cache, the
88 nobarrier option will not lead to filesystem corruption as the
89 pending blocks are supposed to make it to the permanent storage.
90 check_int, check_int_data, check_int_print_mask=value
92 (since: 3.0, default: off)
93 These debugging options control the behavior of the integrity
95 checking module (the BTRFS_FS_CHECK_INTEGRITY config option
96 required). The main goal is to verify that all blocks from a given
97 transaction period are properly linked.
98 check_int enables the integrity checker module, which examines all
100 block write requests to ensure on-disk consistency, at a large
101 memory and CPU cost.
102 check_int_data includes extent data in the integrity checks, and
104 implies the check_int option.
105 check_int_print_mask takes a bitmask of BTRFSIC_PRINT_MASK_* values
107 as defined in fs/btrfs/check-integrity.c, to control the integrity
108 checker module behavior.
109 See comments at the top of fs/btrfs/check-integrity.c for more
111 information.
112 clear_cache
114 Force clearing and rebuilding of the disk space cache if something
115 has gone wrong. See also: space_cache.
116 commit=seconds
118 (since: 3.12, default: 30)
119 Set the interval of periodic transaction commit when data are
121 synchronized to permanent storage. Higher interval values lead to
122 larger amount of unwritten data, which has obvious consequences
123 when the system crashes. The upper bound is not forced, but a
124 warning is printed if it’s more than 300 seconds (5 minutes). Use
125 with care.
126 compress, compress=type, compress-force, compress-force=type
128 (default: off)
129 Control BTRFS file data compression. Type may be specified as zlib,
131 lzo, zstd or no (for no compression, used for remounting). If no
132 type is specified, zlib is used. If compress-force is specified,
133 then compression will always be attempted, but the data may end up
134 uncompressed if the compression would make them larger.
135 Otherwise some simple heuristics are applied to detect an
137 incompressible file. If the first blocks written to a file are not
138 compressible, the whole file is permanently marked to skip
139 compression. As this is too simple, the compress-force is a
140 workaround that will compress most of the files at the cost of some
141 wasted CPU cycles on failed attempts. Since kernel 4.15, a set of
142 heuristic algorithms have been improved by using frequency
143 sampling, repeated pattern detection and Shannon entropy
144 calculation to avoid that.
145 Note
147 If compression is enabled, nodatacow and nodatasum are
148 disabled.
149 datacow, nodatacow
151 (default: on)
152 Enable data copy-on-write for newly created files. Nodatacow
154 implies nodatasum, and disables compression. All files created
155 under nodatacow are also set the NOCOW file attribute (see
156 chattr(1)).
157 Note
159 If nodatacow or nodatasum are enabled, compression is disabled.
160 Updates in-place improve performance for workloads that do frequent
161 overwrites, at the cost of potential partial writes, in case the
162 write is interrupted (system crash, device failure).
163 datasum, nodatasum
165 (default: on)
166 Enable data checksumming for newly created files. Datasum implies
168 datacow, ie. the normal mode of operation. All files created under
169 nodatasum inherit the "no checksums" property, however there’s no
170 corresponding file attribute (see chattr(1)).
171 Note
173 If nodatacow or nodatasum are enabled, compression is disabled.
174 There is a slight performance gain when checksums are turned off,
175 the corresponding metadata blocks holding the checksums do not need
176 to updated. The cost of checksumming of the blocks in memory is
177 much lower than the IO, modern CPUs feature hardware support of the
178 checksumming algorithm.
179 degraded
181 (default: off)
182 Allow mounts with less devices than the RAID profile constraints
184 require. A read-write mount (or remount) may fail when there are
185 too many devices missing, for example if a stripe member is
186 completely missing from RAID0.
187 Since 4.14, the constraint checks have been improved and are
189 verified on the chunk level, not an the device level. This allows
190 degraded mounts of filesystems with mixed RAID profiles for data
191 and metadata, even if the device number constraints would not be
192 satisfied for some of the profiles.
193 Example: metadata — raid1, data — single, devices — /dev/sda,
195 /dev/sdb
196 Suppose the data are completely stored on sda, then missing sdb
198 will not prevent the mount, even if 1 missing device would normally
199 prevent (any) single profile to mount. In case some of the data
200 chunks are stored on sdb, then the constraint of single/data is not
201 satisfied and the filesystem cannot be mounted.
202 device=devicepath
204 Specify a path to a device that will be scanned for BTRFS
205 filesystem during mount. This is usually done automatically by a
206 device manager (like udev) or using the btrfs device scan command
207 (eg. run from the initial ramdisk). In cases where this is not
208 possible the device mount option can help.
209 Note
211 booting eg. a RAID1 system may fail even if all filesystem’s
212 device paths are provided as the actual device nodes may not be
213 discovered by the system at that point.
214 discard, nodiscard
216 (default: off)
217 Enable discarding of freed file blocks. This is useful for SSD
219 devices, thinly provisioned LUNs, or virtual machine images;
220 however, every storage layer must support discard for it to work.
221 if the backing device does not support asynchronous queued TRIM,
222 then this operation can severely degrade performance, because a
223 synchronous TRIM operation will be attempted instead. Queued TRIM
224 requires newer than SATA revision 3.1 chipsets and devices.
225 If it is not necessary to immediately discard freed blocks, then the
227 fstrim tool can be used to discard all free blocks in a batch.
228 Scheduling a TRIM during a period of low system activity will prevent
229 latent interference with the performance of other operations. Also, a
230 device may ignore the TRIM command if the range is too small, so
231 running a batch discard has a greater probability of actually
232 discarding the blocks.
233 If discarding is not necessary to be done at the block freeing time,
235 there’s fstrim(8) tool that lets the filesystem discard all free blocks
236 in a batch, possibly not much interfering with other operations. Also,
237 the device may ignore the TRIM command if the range is too small, so
238 running the batch discard can actually discard the blocks.
239 enospc_debug, noenospc_debug
241 (default: off)
242 Enable verbose output for some ENOSPC conditions. It’s safe to use
244 but can be noisy if the system reaches near-full state.
245 fatal_errors=action
247 (since: 3.4, default: bug)
248 Action to take when encountering a fatal error.
250 bug
252 BUG() on a fatal error, the system will stay in the crashed
253 state and may be still partially usable, but reboot is required
254 for full operation
255 panic
257 panic() on a fatal error, depending on other system
258 configuration, this may be followed by a reboot. Please refer
259 to the documentation of kernel boot parameters, eg. panic,
260 oops or crashkernel.
261 flushoncommit, noflushoncommit
263 (default: off)
264 This option forces any data dirtied by a write in a prior
266 transaction to commit as part of the current commit, effectively a
267 full filesystem sync.
268 This makes the committed state a fully consistent view of the file
270 system from the application’s perspective (i.e. it includes all
271 completed file system operations). This was previously the behavior
272 only when a snapshot was created.
273 When off, the filesystem is consistent but buffered writes may last
275 more than one transaction commit.
276 fragment=type
278 (depends on compile-time option BTRFS_DEBUG, since: 4.4, default:
279 off)
280 A debugging helper to intentionally fragment given type of block
282 groups. The type can be data, metadata or all. This mount option
283 should not be used outside of debugging environments and is not
284 recognized if the kernel config option BTRFS_DEBUG is not enabled.
285 inode_cache, noinode_cache
287 (since: 3.0, default: off)
288 Enable free inode number caching. Not recommended to use unless
290 files on your filesystem get assigned inode numbers that are
291 approaching 2^64. Normally, new files in each subvolume get
292 assigned incrementally (plus one from the last time) and are not
293 reused. The mount option turns on caching of the existing inode
294 numbers and reuse of inode numbers of deleted files.
295 This option may slow down your system at first run, or after
297 mounting without the option.
298 Note
300 Defaults to off due to a potential overflow problem when the
301 free space checksums don’t fit inside a single page.
302 Don’t use this option unless you really need it. The inode number
303 limit on 64bit system is 2^64, which is practically enough for the
304 whole filesystem lifetime. Due to implementation of linux VFS
305 layer, the inode numbers on 32bit systems are only 32 bits wide.
306 This lowers the limit significantly and makes it possible to reach
307 it. In such case, this mount option will help. Alternatively, files
308 with high inode numbers can be copied to a new subvolume which will
309 effectively start the inode numbers from the beginning again.
310 logreplay, nologreplay
312 (default: on, even read-only)
313 Enable/disable log replay at mount time. See also treelog. Note
315 that nologreplay is the same as norecovery.
316 Warning
318 currently, the tree log is replayed even with a read-only
319 mount! To disable that behaviour, mount also with nologreplay.
320 max_inline=bytes
322 (default: min(2048, page size) )
323 Specify the maximum amount of space, that can be inlined in a
325 metadata B-tree leaf. The value is specified in bytes, optionally
326 with a K suffix (case insensitive). In practice, this value is
327 limited by the filesystem block size (named sectorsize at mkfs
328 time), and memory page size of the system. In case of sectorsize
329 limit, there’s some space unavailable due to leaf headers. For
330 example, a 4k sectorsize, maximum size of inline data is about 3900
331 bytes.
332 Inlining can be completely turned off by specifying 0. This will
334 increase data block slack if file sizes are much smaller than block
335 size but will reduce metadata consumption in return.
336 Note
338 the default value has changed to 2048 in kernel 4.6.
339 metadata_ratio=value
341 (default: 0, internal logic)
342 Specifies that 1 metadata chunk should be allocated after every
344 value data chunks. Default behaviour depends on internal logic,
345 some percent of unused metadata space is attempted to be maintained
346 but is not always possible if there’s not enough space left for
347 chunk allocation. The option could be useful to override the
348 internal logic in favor of the metadata allocation if the expected
349 workload is supposed to be metadata intense (snapshots, reflinks,
350 xattrs, inlined files).
351 norecovery
353 (since: 4.5, default: off)
354 Do not attempt any data recovery at mount time. This will disable
356 logreplay and avoids other write operations. Note that this option
357 is the same as nologreplay.
358 Note
360 The opposite option recovery used to have different meaning but
361 was changed for consistency with other filesystems, where
362 norecovery is used for skipping log replay. BTRFS does the same
363 and in general will try to avoid any write operations.
364 rescan_uuid_tree
366 (since: 3.12, default: off)
367 Force check and rebuild procedure of the UUID tree. This should not
369 normally be needed.
370 skip_balance
372 (since: 3.3, default: off)
373 Skip automatic resume of an interrupted balance operation. The
375 operation can later be resumed with btrfs balance resume, or the
376 paused state can be removed with btrfs balance cancel. The default
377 behaviour is to resume an interrupted balance immediately after a
378 volume is mounted.
379 space_cache, space_cache=version, nospace_cache
381 (nospace_cache since: 3.2, space_cache=v1 and space_cache=v2 since
382 4.5, default: space_cache=v1)
383 Options to control the free space cache. The free space cache
385 greatly improves performance when reading block group free space
386 into memory. However, managing the space cache consumes some
387 resources, including a small amount of disk space.
388 There are two implementations of the free space cache. The original
390 one, referred to as v1, is the safe default. The v1 space cache can
391 be disabled at mount time with nospace_cache without clearing.
392 On very large filesystems (many terabytes) and certain workloads,
394 the performance of the v1 space cache may degrade drastically. The
395 v2 implementation, which adds a new B-tree called the free space
396 tree, addresses this issue. Once enabled, the v2 space cache will
397 always be used and cannot be disabled unless it is cleared. Use
398 clear_cache,space_cache=v1 or clear_cache,nospace_cache to do so.
399 If v2 is enabled, kernels without v2 support will only be able to
400 mount the filesystem in read-only mode. The btrfs(8) command
401 currently only has read-only support for v2. A read-write command
402 may be run on a v2 filesystem by clearing the cache, running the
403 command, and then remounting with space_cache=v2.
404 If a version is not explicitly specified, the default
406 implementation will be chosen, which is v1.
407 ssd, ssd_spread, nossd, nossd_spread
409 (default: SSD autodetected)
410 Options to control SSD allocation schemes. By default, BTRFS will
412 enable or disable SSD optimizations depending on status of a device
413 with respect to rotational or non-rotational type. This is
414 determined by the contents of /sys/block/DEV/queue/rotational). If
415 it is 0, the ssd option is turned on. The option nossd will disable
416 the autodetection.
417 The optimizations make use of the absence of the seek penalty
419 that’s inherent for the rotational devices. The blocks can be
420 typically written faster and are not offloaded to separate threads.
421 Note
423 Since 4.14, the block layout optimizations have been dropped.
424 This used to help with first generations of SSD devices. Their
425 FTL (flash translation layer) was not effective and the
426 optimization was supposed to improve the wear by better
427 aligning blocks. This is no longer true with modern SSD devices
428 and the optimization had no real benefit. Furthermore it caused
429 increased fragmentation. The layout tuning has been kept intact
430 for the option ssd_spread.
431 The ssd_spread mount option attempts to allocate into bigger and
432 aligned chunks of unused space, and may perform better on low-end
433 SSDs. ssd_spread implies ssd, enabling all other SSD heuristics as
434 well. The option nossd will disable all SSD options while
435 nossd_spread only disables ssd_spread.
436 subvol=path
438 Mount subvolume from path rather than the toplevel subvolume. The
439 path is always treated as relative to the toplevel subvolume. This
440 mount option overrides the default subvolume set for the given
441 filesystem.
442 subvolid=subvolid
444 Mount subvolume specified by a subvolid number rather than the
445 toplevel subvolume. You can use btrfs subvolume list of btrfs
446 subvolume show to see subvolume ID numbers. This mount option
447 overrides the default subvolume set for the given filesystem.
448 Note
450 if both subvolid and subvol are specified, they must point at
451 the same subvolume, otherwise the mount will fail.
452 thread_pool=number
454 (default: min(NRCPUS + 2, 8) )
455 The number of worker threads to start. NRCPUS is number of on-line
457 CPUs detected at the time of mount. Small number leads to less
458 parallelism in processing data and metadata, higher numbers could
459 lead to a performance hit due to increased locking contention,
460 process scheduling, cache-line bouncing or costly data transfers
461 between local CPU memories.
462 treelog, notreelog
464 (default: on)
465 Enable the tree logging used for fsync and O_SYNC writes. The tree
467 log stores changes without the need of a full filesystem sync. The
468 log operations are flushed at sync and transaction commit. If the
469 system crashes between two such syncs, the pending tree log
470 operations are replayed during mount.
471 Warning
473 currently, the tree log is replayed even with a read-only
474 mount! To disable that behaviour, also mount with nologreplay.
475 The tree log could contain new files/directories, these would not
476 exist on a mounted filesystem if the log is not replayed.
477 usebackuproot, nousebackuproot
479 (since: 4.6, default: off)
480 Enable autorecovery attempts if a bad tree root is found at mount
482 time. Currently this scans a backup list of several previous tree
483 roots and tries to use the first readable. This can be used with
484 read-only mounts as well.
485 Note
487 This option has replaced recovery.
488 user_subvol_rm_allowed
490 (default: off)
491 Allow subvolumes to be deleted by their respective owner.
493 Otherwise, only the root user can do that.
494 Note
496 historically, any user could create a snapshot even if he was
497 not owner of the source subvolume, the subvolume deletion has
498 been restricted for that reason. The subvolume creation has
499 been restricted but this mount option is still required. This
500 is a usability issue. Since 4.18, the rmdir(2) syscall can
501 delete an empty subvolume just like an ordinary directory.
502 Whether this is possible can be detected at runtime, see
503 rmdir_subvol feature in FILESYSTEM FEATURES.
504 DEPRECATED MOUNT OPTIONS
506 List of mount options that have been removed, kept for backward
507 compatibility.
508 alloc_start=bytes
510 (default: 1M, minimum: 1M, deprecated since: 4.13)
511 Debugging option to force all block allocations above a certain
513 byte threshold on each block device. The value is specified in
514 bytes, optionally with a K, M, or G suffix (case insensitive).
515 recovery
517 (since: 3.2, default: off, deprecated since: 4.5)
518 Note
520 this option has been replaced by usebackuproot and should not
521 be used but will work on 4.5+ kernels.
522 subvolrootid=objectid
524 (irrelevant since: 3.2, formally deprecated since: 3.10)
525 A workaround option from times (pre 3.2) when it was not possible
527 to mount a subvolume that did not reside directly under the
528 toplevel subvolume.
529 NOTES ON GENERIC MOUNT OPTIONS
531 Some of the general mount options from mount(8) that affect BTRFS and
532 are worth mentioning.
533 noatime
535 under read intensive work-loads, specifying noatime significantly
536 improves performance because no new access time information needs
537 to be written. Without this option, the default is relatime, which
538 only reduces the number of inode atime updates in comparison to the
539 traditional strictatime. The worst case for atime updates under
540 relatime occurs when many files are read whose atime is older than
541 24 h and which are freshly snapshotted. In that case the atime is
542 updated and COW happens - for each file - in bulk. See also
543 https://lwn.net/Articles/499293/ - Atime and btrfs: a bad
544 combination? (LWN, 2012-05-31).
545 Note that noatime may break applications that rely on atime uptimes
547 like the venerable Mutt (unless you use maildir mailboxes).
548
550 The basic set of filesystem features gets extended over time. The
551 backward compatibility is maintained and the features are optional,
552 need to be explicitly asked for so accidental use will not create
553 incompatibilities.
554 There are several classes and the respective tools to manage the
556 features:
557 at mkfs time only
559 This is namely for core structures, like the b-tree nodesize, see
560 mkfs.btrfs(8) for more details.
561 after mkfs, on an unmounted filesystem
563 Features that may optimize internal structures or add new
564 structures to support new functionality, see btrfstune(8). The
565 command btrfs inspect-internal dump-super device will dump a
566 superblock, you can map the value of incompat_flags to the features
567 listed below
568 after mkfs, on a mounted filesystem
570 The features of a filesystem (with a given UUID) are listed in
571 /sys/fs/btrfs/UUID/features/, one file per feature. The status is
572 stored inside the file. The value 1 is for enabled and active,
573 while 0 means the feature was enabled at mount time but turned off
574 afterwards.
575 Whether a particular feature can be turned on a mounted filesystem
577 can be found in the directory /sys/fs/btrfs/features/, one file per
578 feature. The value 1 means the feature can be enabled.
579 List of features (see also mkfs.btrfs(8) section FILESYSTEM FEATURES):
581 big_metadata
583 (since: 3.4)
584 the filesystem uses nodesize for metadata blocks, this can be
586 bigger than the page size
587 compress_lzo
589 (since: 2.6.38)
590 the lzo compression has been used on the filesystem, either as a
592 mount option or via btrfs filesystem defrag.
593 compress_zstd
595 (since: 4.14)
596 the zstd compression has been used on the filesystem, either as a
598 mount option or via btrfs filesystem defrag.
599 default_subvol
601 (since: 2.6.34)
602 the default subvolume has been set on the filesystem
604 extended_iref
606 (since: 3.7)
607 increased hardlink limit per file in a directory to 65536, older
609 kernels supported a varying number of hardlinks depending on the
610 sum of all file name sizes that can be stored into one metadata
611 block
612 metadata_uuid
614 (since: 5.0)
615 the main filesystem UUID is the metadata_uuid, which stores the new
617 UUID only in the superblock while all metadata blocks still have
618 the UUID set at mkfs time, see btrfstune(8) for more
619 mixed_backref
621 (since: 2.6.31)
622 the last major disk format change, improved backreferences, now
624 default
625 mixed_groups
627 (since: 2.6.37)
628 mixed data and metadata block groups, ie. the data and metadata are
630 not separated and occupy the same block groups, this mode is
631 suitable for small volumes as there are no constraints how the
632 remaining space should be used (compared to the split mode, where
633 empty metadata space cannot be used for data and vice versa)
634 on the other hand, the final layout is quite unpredictable and
636 possibly highly fragmented, which means worse performance
637 no_holes
639 (since: 3.14)
640 improved representation of file extents where holes are not
642 explicitly stored as an extent, saves a few percent of metadata if
643 sparse files are used
644 raid56
646 (since: 3.9)
647 the filesystem contains or contained a raid56 profile of block
649 groups
650 rmdir_subvol
652 (since: 4.18)
653 indicate that rmdir(2) syscall can delete an empty subvolume just
655 like an ordinary directory. Note that this feature only depends on
656 the kernel version.
657 skinny_metadata
659 (since: 3.10)
660 reduced-size metadata for extent references, saves a few percent of
662 metadata
663 SWAPFILE SUPPORT
665 The swapfile is supported since kernel 5.0. Use swapon(8) to activate
666 the swapfile. There are some limitations of the implementation in btrfs
667 and linux swap subystem:
668 + * filesystem - must be only single device * swapfile - the containing
670 subvolume cannot be snapshotted * swapfile - must be preallocated *
671 swapfile - must be nodatacow (ie. also nodatasum) * swapfile - must not
672 be compressed
673 + The limitations come namely from the COW-based design and mapping
675 layer of blocks that allows the advanced features like relocation and
676 multi-device filesystems. However, the swap subsystem expects simpler
677 mapping and no background changes of the file blocks once they’ve been
678 attached to swap.
679 + With active swapfiles, the following whole-filesystem operations will
681 skip swapfile extents or may fail: * balance - block groups with
682 swapfile extents are skipped and reported, the rest will be processed
683 normally * resize grow - unaffected * resize shrink - works as long as
684 the extents are outside of the shrunk range * device add - a new device
685 does not interfere with existing swapfile and this operation will work,
686 though no new swapfile can be activated afterwards * device delete - if
687 the device has been added as above, it can be also deleted * device
688 replace - dtto
689 + When there are no active swapfiles and a whole-filesystem exclusive
691 operation is running (ie. balance, device delete, shrink), the
692 swapfiles cannot be temporarily activated. The operation must finish
693 first.
694 +
696 # truncate -s 0 swapfile
698 # chattr +C swapfile
699 # fallocate -l 2G swapfile
700 # chmod 0600 swapfile
701 # mkswap swapfile
702 # swapon swapfile
703
705 maximum file name length
706 255
707 maximum symlink target length
709 depends on the nodesize value, for 4k it’s 3949 bytes, for larger
710 nodesize it’s 4095 due to the system limit PATH_MAX
711 The symlink target may not be a valid path, ie. the path name
713 components can exceed the limits (NAME_MAX), there’s no content
714 validation at symlink(3) creation.
715 maximum number of inodes
717 2^64 but depends on the available metadata space as the inodes are
718 created dynamically
719 inode numbers
721 minimum number: 256 (for subvolumes), regular files and
722 directories: 257
723 maximum file length
725 inherent limit of btrfs is 2^64 (16 EiB) but the linux VFS limit is
726 2^63 (8 EiB)
727 maximum number of subvolumes
729 the subvolume ids can go up to 2^64 but the number of actual
730 subvolumes depends on the available metadata space, the space
731 consumed by all subvolume metadata includes bookkeeping of shared
732 extents can be large (MiB, GiB)
733 maximum number of hardlinks of a file in a directory
735 65536 when the extref feature is turned on during mkfs (default),
736 roughly 100 otherwise
737
739 GRUB2 (https://www.gnu.org/software/grub) has the most advanced support
740 of booting from BTRFS with respect to features.
741 EXTLINUX (from the https://syslinux.org project) can boot but does not
743 support all features. Please check the upstream documentation before
744 you use it.
745
747 The btrfs filesystem supports setting the following file attributes
748 using the chattr(1) utility:
749 a
751 append only, new writes are always written at the end of the file
752 A
754 no atime updates
755 c
757 compress data, all data written after this attribute is set will be
758 compressed. Please note that compression is also affected by the
759 mount options or the parent directory attributes.
760 When set on a directory, all newly created files will inherit this
762 attribute.
763 C
765 no copy-on-write, file modifications are done in-place
766 When set on a directory, all newly created files will inherit this
768 attribute.
769 Note
771 due to implementation limitations, this flag can be set/unset
772 only on empty files.
773 d
775 no dump, makes sense with 3rd party tools like dump(8), on BTRFS
776 the attribute can be set/unset but no other special handling is
777 done
778 D
780 synchronous directory updates, for more details search open(2) for
781 O_SYNC and O_DSYNC
782 i
784 immutable, no file data and metadata changes allowed even to the
785 root user as long as this attribute is set (obviously the exception
786 is unsetting the attribute)
787 S
789 synchronous updates, for more details search open(2) for O_SYNC and
790 O_DSYNC
791 X
793 no compression, permanently turn off compression on the given file.
794 Any compression mount options will not affect this file.
795 When set on a directory, all newly created files will inherit this
797 attribute.
798 No other attributes are supported. For the complete list please refer
800 to the chattr(1) manual page.
801
803 There’s a character special device /dev/btrfs-control with major and
804 minor numbers 10 and 234 (the device can be found under the misc
805 category).
806 $ ls -l /dev/btrfs-control
808 crw------- 1 root root 10, 234 Jan 1 12:00 /dev/btrfs-control
809 The device accepts some ioctl calls that can perform following actions
811 on the filesystem module:
812 · scan devices for btrfs filesystem (ie. to let multi-device
814 filesystems mount automatically) and register them with the kernel
815 module
816 · similar to scan, but also wait until the device scanning process is
818 finished for a given filesystem
819 · get the supported features (can be also found under
821 /sys/fs/btrfs/features)
822 The device is usually created by a system device node manager (eg.
824 udev), but can be created manually:
825 # mknod --mode=600 c 10 234 /dev/btrfs-control
827 The control device is not strictly required but the device scanning
829 will not work and a workaround would need to be used to mount a
830 multi-device filesystem. The mount option device can trigger the device
831 scanning during mount.
832
834 acl(5), btrfs(8), chattr(1), fstrim(8), ioctl(2), mkfs.btrfs(8),
835 mount(8), swapon(8)
836Btrfs v5.1 05/31/2019 BTRFS-MAN5(5)