1BTRFS-MAN5(5)                    Btrfs Manual                    BTRFS-MAN5(5)
2
3
4

NAME

6       btrfs-man5 - topics about the BTRFS filesystem (mount options,
7       supported file attributes and other)
8

DESCRIPTION

10       This document describes topics related to BTRFS that are not specific
11       to the tools. Currently covers:
12
13        1. mount options
14
15        2. filesystem features
16
17        3. file attributes
18
19        4. control device
20

MOUNT OPTIONS

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
26       acl, noacl
27           (default: on)
28
29           Enable/disable support for Posix Access Control Lists (ACLs). See
30           the acl(5) manual page for more information about ACLs.
31
32           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
36       alloc_start=bytes
37           (default: 1M, minimum: 1M)
38
39           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
43           This option was used for testing and has no practical use, it’s
44           slated to be removed in the future.
45
46       autodefrag, noautodefrag
47           (since: 3.0, default: off)
48
49           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
54           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
58               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
66       barrier, nobarrier
67           (default: on)
68
69           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
76           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
84           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
88       check_int, check_int_data, check_int_print_mask=value
89           (since: 3.0, default: off)
90
91           These debugging options control the behavior of the integrity
92           checking module (the BTRFS_FS_CHECK_INTEGRITY config option
93           required).
94
95           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
99           check_int_data includes extent data in the integrity checks, and
100           implies the check_int option.
101
102           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
106           See comments at the top of fs/btrfs/check-integrity.c for more
107           info.
108
109       clear_cache
110           Force clearing and rebuilding of the disk space cache if something
111           has gone wrong. See also: space_cache.
112
113       commit=seconds
114           (since: 3.12, default: 30)
115
116           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
121       compress, compress=type, compress-force, compress-force=type
122           (default: off)
123
124           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
132               Note
133               If compression is enabled, nodatacow and nodatasum are
134               disabled.
135
136       datacow, nodatacow
137           (default: on)
138
139           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
144               Note
145               If nodatacow or nodatasum are enabled, compression is disabled.
146
147       datasum, nodatasum
148           (default: on)
149
150           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
155               Note
156               If nodatacow or nodatasum are enabled, compression is disabled.
157
158       degraded
159           (default: off)
160
161           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
166       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
173               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
178       discard, nodiscard
179           (default: off)
180
181           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
188           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
195       enospc_debug, noenospc_debug
196           (default: off)
197
198           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
201       fatal_errors=action
202           (since: 3.4, default: bug)
203
204           Action to take when encountering a fatal error.
205
206           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
211           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
217       flushoncommit, noflushoncommit
218           (default: off)
219
220           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
224           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
229           When off, the filesystem is consistent but buffered writes may last
230           more than one transaction commit.
231
232       fragment=type
233           (depends on compile-time option BTRFS_DEBUG, since: 4.4, default:
234           off)
235
236           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
241       inode_cache, noinode_cache
242           (since: 3.0, default: off)
243
244           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
251           This option may slow down your system at first run, or after
252           mounting without the option.
253
254               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
258       logreplay, nologreplay
259           (default: on, even read-only)
260
261           Enable/disable log replay at mount time. See also treelog.
262
263               Warning
264               currently, the tree log is replayed even with a read-only
265               mount! To disable that behaviour, mount also with nologreplay.
266
267       max_inline=bytes
268           (default: min(2048, page size) )
269
270           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
279           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
283               Note
284               the default value has changed to 2048 in kernel 4.6.
285
286       metadata_ratio=value
287           (default: 0, internal logic)
288
289           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
298       recovery
299           (since: 3.2, default: off, deprecated since: 4.5)
300
301               Note
302               this option has been replaced by usebackuproot and should not
303               be used but will work on 4.5+ kernels.
304
305       norecovery
306           (since: 4.5, default: off)
307
308           Do not attempt any data recovery at mount time. This will disable
309           logreplay and avoids other write operations.
310
311               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
317       rescan_uuid_tree
318           (since: 3.12, default: off)
319
320           Force check and rebuild procedure of the UUID tree. This should not
321           normally be needed.
322
323       skip_balance
324           (since: 3.3, default: off)
325
326           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
331       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
335           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
340           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
344           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
356           If a version is not explicitly specified, the default
357           implementation will be chosen, which is v1 as of 4.9.
358
359       ssd, nossd, ssd_spread
360           (default: SSD autodetected)
361
362           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
368           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
373       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
379       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
385               Note
386               if both subvolid and subvol are specified, they must point at
387               the same subvolume, otherwise mount will fail.
388
389       subvolrootid=objectid
390           (irrelevant since: 3.2, formally deprecated since: 3.10)
391
392           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
396       thread_pool=number
397           (default: min(NRCPUS + 2, 8) )
398
399           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
406       treelog, notreelog
407           (default: on)
408
409           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
415               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
421       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
427               Note
428               This option has replaced recovery.
429
430       user_subvol_rm_allowed
431           (default: off)
432
433           Allow subvolumes to be deleted by their respective owner.
434           Otherwise, only the root user can do that.
435

FILESYSTEM FEATURES

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
442       There are several classes and the respective tools to manage the
443       features:
444
445       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
449       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
456       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
463           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
467       List of features (see also mkfs.btrfs(8) section FILESYSTEM FEATURES):
468
469       big_metadata
470           (since: 3.4)
471
472           the filesystem uses nodesize bigger than the page size
473           compress_lzo:: (since: 2.6.38)
474
475           the lzo compression has been used on the filesystem, either as a
476           mount option or via btrfs filesystem defrag.
477
478       default_subvol
479           (since: 2.6.34)
480
481           the default subvolume has been set on the filesystem
482
483       extended_iref
484           (since: 3.7)
485
486           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
491       mixed_backref
492           (since: 2.6.31)
493
494           the last major disk format change, improved backreferences
495
496       mixed_groups
497           (since: 2.6.37)
498
499           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
505           on the other hand, the final layout is quite unpredictable and
506           possibly highly fragmented, which means worse performance
507
508       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
513       raid56
514           (since: 3.9)
515
516           the filesystem contains or contained a raid56 profile of block
517           groups
518
519       skinny_metadata
520           (since: 3.10)
521
522           reduced-size metadata for extent references, saves a few percent of
523           metadata
524

FILE ATTRIBUTES

526       The btrfs filesystem supports setting the following file attributes
527       using the chattr(1) utility:
528
529       a
530           append only, new writes are always written at the end of the file
531
532       A
533           no atime updates
534
535       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
540           When set on a directory, all newly created files will inherit this
541           attribute.
542
543       C
544           no copy-on-write, file modifications are done in-place
545
546           When set on a directory, all newly created files will inherit this
547           attribute.
548
549               Note
550               due to implementation limitations, this flag can be set/unset
551               only on empty files.
552
553       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
557       D
558           synchronous directory updates, for more details search open(2) for
559           O_SYNC and O_DSYNC
560
561       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
566       S
567           synchronous updates, for more details search open(2) for O_SYNC and
568           O_DSYNC
569
570       X
571           no compression, permanently turn off compression on the given file,
572           other compression mount options will not affect that
573
574           When set on a directory, all newly created files will inherit this
575           attribute.
576
577       No other attributes are supported. For the complete list please refer
578       to the chattr(1) manual page.
579

CONTROL DEVICE

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
585           $ ls -l /dev/btrfs-control
586           crw------- 1 root root 10, 234 Jan  1 12:00 /dev/btrfs-control
587
588       The device accepts some ioctl calls that can perform following actions
589       on the filesyste module:
590
591       ·   scan devices for btrfs filesystem (ie. to let multi-device
592           filesystems mount automatically) and register them with the kernel
593           module
594
595       ·   similar to scan, but also wait until the device scanning process is
596           finished for a given filesystem
597
598       ·   get the supported features (can be also found under
599           /sys/fs/btrfs/features)
600
601       The device is usually created by ..., but can be created manually:
602
603           # mknod --mode=600 c 10 234 /dev/btrfs-control
604
605       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

SEE ALSO

611       acl(5), btrfs(8), chattr(1), fstrim(8), ioctl(2), mkfs.btrfs(8),
612       mount(8)
613
614
615
616Btrfs v4.9.1                      08/06/2017                     BTRFS-MAN5(5)
Impressum