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. file attributes
18 4. control device
20
22 This section describes mount options specific to BTRFS. For the generic
23 mount options please refer to mount(8) manpage. The options are sorted
24 alphabetically (discarding the no prefix).
25 acl, noacl
27 (default: on)
28 Enable/disable support for Posix Access Control Lists (ACLs). See
30 the acl(5) manual page for more information about ACLs.
31 The support for ACL is build-time configurable (BTRFS_FS_POSIX_ACL)
33 and mount fails if acl is requested but the feature is not compiled
34 in.
35 alloc_start=bytes
37 (default: 1M, minimum: 1M)
38 Debugging option to force all block allocations above a certain
40 byte threshold on each block device. The value is specified in
41 bytes, optionally with a K, M, or G suffix (case insensitive).
42 This option was used for testing and has no practical use, it’s
44 slated to be removed in the future.
45 autodefrag, noautodefrag
47 (since: 3.0, default: off)
48 Enable automatic file defragmentation. When enabled, small random
50 writes into files (in a range of tens of kilobytes, currently it’s
51 64K) are detected and queued up for the defragmentation process.
52 Not well suited for large database workloads.
53 The read latency may increase due to reading the adjacent blocks
55 that make up the range for defragmentation, successive write will
56 merge the blocks in the new location.
57 Warning
59 Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as
60 well as with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12
61 or ≥ 3.13.4 will break up the ref-links of CoW data (for
62 example files copied with cp --reflink, snapshots or
63 de-duplicated data). This may cause considerable increase of
64 space usage depending on the broken up ref-links.
65 barrier, nobarrier
67 (default: on)
68 Ensure that all IO write operations make it through the device
70 cache and are stored permanently when the filesystem is at it’s
71 consistency checkpoint. This typically means that a flush command
72 is sent to the device that will synchronize all pending data and
73 ordinary metadata blocks, then writes the superblock and issues
74 another flush.
75 The write flushes incur a slight hit and also prevent the IO block
77 scheduler to reorder requests in a more effective way. Disabling
78 barriers gets rid of that penalty but will most certainly lead to a
79 corrupted filesystem in case of a crash or power loss. The ordinary
80 metadata blocks could be yet unwritten at the time the new
81 superblock is stored permanently, expecting that the block pointers
82 to metadata were stored permanently before.
83 On a device with a volatile battery-backed write-back cache, the
85 nobarrier option will not lead to filesystem corruption as the
86 pending blocks are supposed to make it to the permanent storage.
87 check_int, check_int_data, check_int_print_mask=value
89 (since: 3.0, default: off)
90 These debugging options control the behavior of the integrity
92 checking module (the BTRFS_FS_CHECK_INTEGRITY config option
93 required).
94 check_int enables the integrity checker module, which examines all
96 block write requests to ensure on-disk consistency, at a large
97 memory and CPU cost.
98 check_int_data includes extent data in the integrity checks, and
100 implies the check_int option.
101 check_int_print_mask takes a bitmask of BTRFSIC_PRINT_MASK_* values
103 as defined in fs/btrfs/check-integrity.c, to control the integrity
104 checker module behavior.
105 See comments at the top of fs/btrfs/check-integrity.c for more
107 info.
108 clear_cache
110 Force clearing and rebuilding of the disk space cache if something
111 has gone wrong. See also: space_cache.
112 commit=seconds
114 (since: 3.12, default: 30)
115 Set the interval of periodic commit. Higher values defer data being
117 synced to permanent storage with obvious consequences when the
118 system crashes. The upper bound is not forced, but a warning is
119 printed if it’s more than 300 seconds (5 minutes).
120 compress, compress=type, compress-force, compress-force=type
122 (default: off)
123 Control BTRFS file data compression. Type may be specified as zlib,
125 lzo or no (for no compression, used for remounting). If no type is
126 specified, zlib is used. If compress-force is specified, all files
127 will be compressed, whether or not they compress well. Otherwise
128 some simple heuristics are applied to detect an incompressible
129 file. If the first blocks written to a file are not compressible,
130 the whole file is permanently marked to skip compression.
131 Note
133 If compression is enabled, nodatacow and nodatasum are
134 disabled.
135 datacow, nodatacow
137 (default: on)
138 Enable data copy-on-write for newly created files. Nodatacow
140 implies nodatasum, and disables compression. All files created
141 under nodatacow are also set the NOCOW file attribute (see
142 chattr(1)).
143 Note
145 If nodatacow or nodatasum are enabled, compression is disabled.
146 datasum, nodatasum
148 (default: on)
149 Enable data checksumming for newly created files. Datasum implies
151 datacow, ie. the normal mode of operation. All files created under
152 nodatasum inherit the "no checksums" property, however there’s no
153 corresponding file attribute (see chattr(1)).
154 Note
156 If nodatacow or nodatasum are enabled, compression is disabled.
157 degraded
159 (default: off)
160 Allow mounts with less devices than the raid profile constraints
162 require. A read-write mount (or remount) may fail with too many
163 devices missing, for example if a stripe member is completely
164 missing from RAID0.
165 device=devicepath
167 Specify a path to a device that will be scanned for BTRFS
168 filesystem during mount. This is usually done automatically by a
169 device manager (like udev) or using the btrfs device scan command
170 (eg. run from the initial ramdisk). In cases where this is not
171 possible the device mount option can help.
172 Note
174 booting eg. a RAID1 system may fail even if all filesystem’s
175 device paths are provided as the actual device nodes may not be
176 discovered by the system at that point.
177 discard, nodiscard
179 (default: off)
180 Enable discarding of freed file blocks using TRIM operation. This
182 is useful for SSD devices, thinly provisioned LUNs or virtual
183 machine images where the backing device understands the operation.
184 Depending on support of the underlying device, the operation may
185 severely hurt performance in case the TRIM operation is synchronous
186 (eg. with SATA devices up to revision 3.0).
187 If discarding is not necessary to be done at the block freeing
189 time, there’s fstrim tool that lets the filesystem discard all free
190 blocks in a batch, possibly not much interfering with other
191 operations. Also, the the device may ignore the TRIM command if the
192 range is too small, so running the batch discard can actually
193 discard the blocks.
194 enospc_debug, noenospc_debug
196 (default: off)
197 Enable verbose output for some ENOSPC conditions. It’s safe to use
199 but can be noisy if the system reaches near-full state.
200 fatal_errors=action
202 (since: 3.4, default: bug)
203 Action to take when encountering a fatal error.
205 bug
207 BUG() on a fatal error, the system will stay in the crashed
208 state and may be still partially usable, but reboot is required
209 for full operation
210 panic
212 panic() on a fatal error, depending on other system
213 configuration, this may be followed by a reboot. Please refer
214 to the documentation of kernel boot parameters, eg. panic,
215 oops or crashkernel.
216 flushoncommit, noflushoncommit
218 (default: off)
219 This option forces any data dirtied by a write in a prior
221 transaction to commit as part of the current commit, effectively a
222 full filesystem sync.
223 This makes the committed state a fully consistent view of the file
225 system from the application’s perspective (i.e., it includes all
226 completed file system operations). This was previously the behavior
227 only when a snapshot was created.
228 When off, the filesystem is consistent but buffered writes may last
230 more than one transaction commit.
231 fragment=type
233 (depends on compile-time option BTRFS_DEBUG, since: 4.4, default:
234 off)
235 A debugging helper to intentionally fragment given type of block
237 groups. The type can be data, metadata or all. This mount option
238 should not be used outside of debugging environments and is not
239 recognized if the kernel config option BTRFS_DEBUG is not enabled.
240 inode_cache, noinode_cache
242 (since: 3.0, default: off)
243 Enable free inode number caching. Not recommended to use unless
245 files on your filesystem get assigned inode numbers that are
246 approaching 264. Normally, new files in each subvolume get assigned
247 incrementally (plus one from the last time) and are not reused. The
248 mount option turns on caching of the existing inode numbers and
249 reuse of inode numbers of deleted files.
250 This option may slow down your system at first run, or after
252 mounting without the option.
253 Note
255 Defaults to off due to a potential overflow problem when the
256 free space checksums don’t fit inside a single page.
257 logreplay, nologreplay
259 (default: on, even read-only)
260 Enable/disable log replay at mount time. See also treelog.
262 Warning
264 currently, the tree log is replayed even with a read-only
265 mount! To disable that behaviour, mount also with nologreplay.
266 max_inline=bytes
268 (default: min(2048, page size) )
269 Specify the maximum amount of space, in bytes, that can be inlined
271 in a metadata B-tree leaf. The value is specified in bytes,
272 optionally with a K suffix (case insensitive). In practice, this
273 value is limited by the filesystem block size (named sectorsize at
274 mkfs time), and memory page size of the system. In case of
275 sectorsize limit, there’s some space unavailable due to leaf
276 headers. For example, a 4k sectorsize, maximum size of inline data
277 is about 3900 bytes.
278 Inlining can be completely turned off by specifying 0. This will
280 increase data block slack if file sizes are much smaller than block
281 size but will reduce metadata consumption in return.
282 Note
284 the default value has changed to 2048 in kernel 4.6.
285 metadata_ratio=value
287 (default: 0, internal logic)
288 Specifies that 1 metadata chunk should be allocated after every
290 value data chunks. Default behaviour depends on internal logic,
291 some percent of unused metadata space is attempted to be maintained
292 but is not always possible if there’s not enough space left for
293 chunk allocation. The option could be useful to override the
294 internal logic in favor of the metadata allocation if the expected
295 workload is supposed to be metadata intense (snapshots, reflinks,
296 xattrs, inlined files).
297 recovery
299 (since: 3.2, default: off, deprecated since: 4.5)
300 Note
302 this option has been replaced by usebackuproot and should not
303 be used but will work on 4.5+ kernels.
304 norecovery
306 (since: 4.5, default: off)
307 Do not attempt any data recovery at mount time. This will disable
309 logreplay and avoids other write operations.
310 Note
312 The opposite option recovery used to have different meaning but
313 was changed for consistency with other filesystems, where
314 norecovery is used for skipping log replay. BTRFS does the same
315 and in general will try to avoid any write operations.
316 rescan_uuid_tree
318 (since: 3.12, default: off)
319 Force check and rebuild procedure of the UUID tree. This should not
321 normally be needed.
322 skip_balance
324 (since: 3.3, default: off)
325 Skip automatic resume of interrupted balance operation after mount.
327 May be resumed with btrfs balance resume or the paused state can be
328 removed by btrfs balance cancel. The default behaviour is to start
329 interrutpd balance.
330 space_cache, space_cache=version, nospace_cache
332 (nospace_cache since: 3.2, space_cache=v1 and space_cache=v2 since
333 4.5, default: space_cache=v1)
334 Options to control the free space cache. The free space cache
336 greatly improves performance when reading block group free space
337 into memory. However, managing the space cache consumes some
338 resources, including a small amount of disk space.
339 There are two implementations of the free space cache. The original
341 implementation, v1, is the safe default. The v1 space cache can be
342 disabled at mount time with nospace_cache without clearing.
343 On very large filesystems (many terabytes) and certain workloads,
345 the performance of the v1 space cache may degrade drastically. The
346 v2 implementation, which adds a new B-tree called the free space
347 tree, addresses this issue. Once enabled, the v2 space cache will
348 always be used and cannot be disabled unless it is cleared. Use
349 clear_cache,space_cache=v1 or clear_cache,nospace_cache to do so.
350 If v2 is enabled, kernels without v2 support will only be able to
351 mount the filesystem in read-only mode. The btrfs(8) command
352 currently only has read-only support for v2. A read-write command
353 may be run on a v2 filesystem by clearing the cache, running the
354 command, and then remounting with space_cache=v2.
355 If a version is not explicitly specified, the default
357 implementation will be chosen, which is v1 as of 4.9.
358 ssd, nossd, ssd_spread
360 (default: SSD autodetected)
361 Options to control SSD allocation schemes. By default, BTRFS will
363 enable or disable SSD allocation heuristics depending on whether a
364 rotational or non-rotational disk is in use (contents of
365 /sys/block/DEV/queue/rotational). The ssd and nossd options can
366 override this autodetection.
367 The ssd_spread mount option attempts to allocate into bigger and
369 aligned chunks of unused space, and may perform better on low-end
370 SSDs. ssd_spread implies ssd, enabling all other SSD heuristics as
371 well.
372 subvol=path
374 Mount subvolume from path rather than the toplevel subvolume. The
375 path is absolute (ie. starts at the toplevel subvolume). This mount
376 option overrides the default subvolume set for the given
377 filesystem.
378 subvolid=subvolid
380 Mount subvolume specified by a subvolid number rather than the
381 toplevel subvolume. You can use btrfs subvolume list to see
382 subvolume ID numbers. This mount option overrides the default
383 subvolume set for the given filesystem.
384 Note
386 if both subvolid and subvol are specified, they must point at
387 the same subvolume, otherwise mount will fail.
388 subvolrootid=objectid
390 (irrelevant since: 3.2, formally deprecated since: 3.10)
391 A workaround option from times (pre 3.2) when it was not possible
393 to mount a subvolume that did not reside directly under the
394 toplevel subvolume.
395 thread_pool=number
397 (default: min(NRCPUS + 2, 8) )
398 The number of worker threads to allocate. NRCPUS is number of
400 on-line CPUs detected at the time of mount. Small number leads to
401 less parallelism in processing data and metadata, higher numbers
402 could lead to a performance hit due to increased locking
403 contention, cache-line bouncing or costly data transfers between
404 local CPU memories.
405 treelog, notreelog
407 (default: on)
408 Enable the tree logging used for fsync and O_SYNC writes. The tree
410 log stores changes without the need of a full filesystem sync. The
411 log operations are flushed at sync and transaction commit. If the
412 system crashes between two such syncs, the pending tree log
413 operations are replayed during mount.
414 Warning
416 currently, the tree log is replayed even with a read-only
417 mount! To disable that behaviour, mount also with nologreplay.
418 The tree log could contain new files/directories, these would not
419 exist on a mounted filesystem if the log is not replayed.
420 usebackuproot, nousebackuproot
422 Enable autorecovery attempts if a bad tree root is found at mount
423 time. Currently this scans a backup list of several previous tree
424 roots and tries to use the first readable. This can be used with
425 read-only mounts as well.
426 Note
428 This option has replaced recovery.
429 user_subvol_rm_allowed
431 (default: off)
432 Allow subvolumes to be deleted by their respective owner.
434 Otherwise, only the root user can do that.
435
437 The basic set of filesystem features gets extended over time. The
438 backward compatibility is maintained and the features are optional,
439 need to be explicitly asked for so accidental use will not create
440 incompatibilities.
441 There are several classes and the respective tools to manage the
443 features:
444 at mkfs time only
446 This is namely for core structures, like the b-tree nodesize, see
447 mkfs.btrfs(8) for more details.
448 after mkfs, on an unmounted filesystem
450 Features that may optimize internal structures or add new
451 structures to support new functionality, see btrfstune(8). The
452 command btrfs inspect-internal dump-super device will dump a
453 superblock, you can map the value of incompat_flags to the features
454 listed below
455 after mkfs, on a mounted filesystem
457 The features of a filesystem (with a given UUID) are listed in
458 /sys/fs/btrfs/UUID/features/, one file per feature. The status of
459 is stored insid the file. The value 1 is for enabled, 0 means the
460 feature had been enabled at the mount time and turned off
461 afterwards.
462 Whether a particular feature can be turned on a mounted filesystem
464 can be found in the directory /sys/fs/btrfs/features/, one file per
465 feature. The value 1 means the feature can be enabled.
466 List of features (see also mkfs.btrfs(8) section FILESYSTEM FEATURES):
468 big_metadata
470 (since: 3.4)
471 the filesystem uses nodesize bigger than the page size
473 compress_lzo:: (since: 2.6.38)
474 the lzo compression has been used on the filesystem, either as a
476 mount option or via btrfs filesystem defrag.
477 default_subvol
479 (since: 2.6.34)
480 the default subvolume has been set on the filesystem
482 extended_iref
484 (since: 3.7)
485 increased hardlink limit per file in a directory to 65536, older
487 kernels supported a varying number of hardlinks depending on the
488 sum of all file name sizes that can be stored into one metadata
489 block
490 mixed_backref
492 (since: 2.6.31)
493 the last major disk format change, improved backreferences
495 mixed_groups
497 (since: 2.6.37)
498 mixed data and metadata block groups, ie. the data and metadata are
500 not separated and occupy the same block groups, this mode is
501 suitable for small volumes as there are no constraints how the
502 remaining space should be used (compared to the split mode, where
503 empty metadata space cannot be used for data and vice versa)
504 on the other hand, the final layout is quite unpredictable and
506 possibly highly fragmented, which means worse performance
507 no_holes
509 (since: 3.14) improved representation of file extents where holes
510 are not explicitly stored as an extent, saves a few percent of
511 metadata if sparse files are used
512 raid56
514 (since: 3.9)
515 the filesystem contains or contained a raid56 profile of block
517 groups
518 skinny_metadata
520 (since: 3.10)
521 reduced-size metadata for extent references, saves a few percent of
523 metadata
524
526 The btrfs filesystem supports setting the following file attributes
527 using the chattr(1) utility:
528 a
530 append only, new writes are always written at the end of the file
531 A
533 no atime updates
534 c
536 compress data, all data written after this attribute is set will be
537 compressed. Please note that compression is also affected by the
538 mount options or the parent directory attributes.
539 When set on a directory, all newly created files will inherit this
541 attribute.
542 C
544 no copy-on-write, file modifications are done in-place
545 When set on a directory, all newly created files will inherit this
547 attribute.
548 Note
550 due to implementation limitations, this flag can be set/unset
551 only on empty files.
552 d
554 no dump, makes sense with 3rd party tools like dump(8), on BTRFS
555 the attribute can be set/unset on no other special handling is done
556 D
558 synchronous directory updates, for more details search open(2) for
559 O_SYNC and O_DSYNC
560 i
562 immutable, no file data and metadata changes allowed even to the
563 root user as long as this attribute is set (obviously the exception
564 is unsetting the attribute)
565 S
567 synchronous updates, for more details search open(2) for O_SYNC and
568 O_DSYNC
569 X
571 no compression, permanently turn off compression on the given file,
572 other compression mount options will not affect that
573 When set on a directory, all newly created files will inherit this
575 attribute.
576 No other attributes are supported. For the complete list please refer
578 to the chattr(1) manual page.
579
581 There’s a character special device /dev/btrfs-control with major and
582 minor numbers 10 and 234 (the device can be found under the misc
583 category).
584 $ ls -l /dev/btrfs-control
586 crw------- 1 root root 10, 234 Jan 1 12:00 /dev/btrfs-control
587 The device accepts some ioctl calls that can perform following actions
589 on the filesyste module:
590 · scan devices for btrfs filesystem (ie. to let multi-device
592 filesystems mount automatically) and register them with the kernel
593 module
594 · similar to scan, but also wait until the device scanning process is
596 finished for a given filesystem
597 · get the supported features (can be also found under
599 /sys/fs/btrfs/features)
600 The device is usually created by ..., but can be created manually:
602 # mknod --mode=600 c 10 234 /dev/btrfs-control
604 The device is not strictly required but the device scanning will not
606 work and a workaround would need to be used to mount a multi-device
607 filesystem. The mount option device can trigger the device scanning
608 during mount.
609
611 acl(5), btrfs(8), chattr(1), fstrim(8), ioctl(2), mkfs.btrfs(8),
612 mount(8)
613Btrfs v4.9.1 08/06/2017 BTRFS-MAN5(5)