Documentation/btrfs-man5.asciidoc

   1 btrfs-man5(5)
   2 ==============
   3
   4 NAME
   5 ----
   6 btrfs-man5 - topics about the BTRFS filesystem (mount options, supported file attributes and other)
   7
   8 DESCRIPTION
   9 -----------
  10 This document describes topics related to BTRFS that are not specific to the
  11 tools.  Currently covers:
  12
  13 1. mount options
  14
  15 2. file attributes
  16
  17 MOUNT OPTIONS
  18 -------------
  19
  20 This section describes mount options specific to BTRFS.  For the generic mount
  21 options please refer to `mount`(8) manpage. The options are sorted alphabetically
  22 (discarding the 'no' prefix).
  23
  24 *acl*::
  25 *noacl*::
  26 (default: on)
  27 +
  28 Enable/disable support for Posix Access Control Lists (ACLs).  See the
  29 `acl`(5) manual page for more information about ACLs.
  30
  31 *alloc_start='bytes'*::
  32 (default: 1M, minimum: 1M)
  33 +
  34 Debugging option to force all block allocations above a certain
  35 byte threshold on each block device.  The value is specified in
  36 bytes, optionally with a K, M, or G suffix (case insensitive).
  37 +
  38 This option was used for testing and has no practical use, it's slated to be
  39 removed in the future.
  40
  41 *autodefrag*::
  42 *noautodefrag*::
  43 (since: 3.0, default: off)
  44 +
  45 Enable automatic file defragmentation.
  46 When enabled, small random writes into files (in a range of tens of kilobytes,
  47 currently it's 64K) are detected and queued up for the defragmentation process.
  48 Not well suited for large database workloads.
  49 +
  50 The read latency may increase due to reading the adjacent blocks that make up the
  51 range for defragmentation, successive write will merge the blocks in the new
  52 location.
  53 +
  54 WARNING: Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as
  55 well as with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or
  56 ≥ 3.13.4 will break up the ref-links of CoW data (for example files
  57 copied with `cp --reflink`, snapshots or de-duplicated data).
  58 This may cause considerable increase of space usage depending on the
  59 broken up ref-links.
  60
  61 *barrier*::
  62 *nobarrier*::
  63 (default: on)
  64 +
  65 Ensure that all IO write operations make it through the device cache and are stored
  66 permanently when the filesystem is at it's consistency checkpoint. This
  67 typically means that a flush command is sent to the device that will
  68 synchronize all pending data and ordinary metadata blocks, then writes the
  69 superblock and issues another flush.
  70 +
  71 The write flushes incur a slight hit and also prevent the IO block
  72 scheduler to reorder requests in more effective way. Disabling barriers gets
  73 rid of that penalty but will most certainly lead to a corrupted filesystem in
  74 case of a crash or power loss. The ordinary metadata blocks could be yet
  75 unwritten at the time the new superblock is stored permanently, expecting that
  76 the block pointers to metadata were stored permanently before.
  77 +
  78 On a device with a volatile battery-backed write-back cache, the 'nobarrier'
  79 option will not lead to filesystem corruption as the pending blocks are
  80 supposed to make it to the permanent storage.
  81
  82 *check_int*::
  83 *check_int_data*::
  84 *check_int_print_mask='value'*::
  85 (since: 3.0, default: off)
  86 +
  87 These debugging options control the behavior of the integrity checking
  88 module (the BTRFS_FS_CHECK_INTEGRITY config option required). +
  89 +
  90 `check_int` enables the integrity checker module, which examines all
  91 block write requests to ensure on-disk consistency, at a large
  92 memory and CPU cost. +
  93 +
  94 `check_int_data` includes extent data in the integrity checks, and
  95 implies the check_int option. +
  96 +
  97 `check_int_print_mask` takes a bitmask of BTRFSIC_PRINT_MASK_* values
  98 as defined in 'fs/btrfs/check-integrity.c', to control the integrity
  99 checker module behavior. +
 100 +
 101 See comments at the top of 'fs/btrfs/check-integrity.c'
 102 for more info.
 103
 104 *clear_cache*::
 105 Force clearing and rebuilding of the disk space cache if something
 106 has gone wrong. See also: 'space_cache'.
 107
 108 *commit='seconds'*::
 109 (since: 3.12, default: 30)
 110 +
 111 Set the interval of periodic commit. Higher
 112 values defer data being synced to permanent storage with obvious
 113 consequences when the system crashes. The upper bound is not forced,
 114 but a warning is printed if it's more than 300 seconds (5 minutes).
 115
 116 *compress*::
 117 *compress='type'*::
 118 *compress-force*::
 119 *compress-force='type'*::
 120 (default: off)
 121 +
 122 Control BTRFS file data compression.  Type may be specified as 'zlib',
 123 'lzo' or 'no' (for no compression, used for remounting).  If no type
 124 is specified, 'zlib' is used.  If compress-force is specified,
 125 all files will be compressed, whether or not they compress well.
 126 +
 127 NOTE: If compression is enabled, 'nodatacow' and 'nodatasum' are disabled.
 128
 129 *datacow*::
 130 *nodatacow*::
 131 (default: on)
 132 +
 133 Enable data copy-on-write for newly created files.
 134 'Nodatacow' implies 'nodatasum', and disables 'compression'. All files created
 135 under 'nodatacow' are also set the NOCOW file attribute (see `chattr`(1)).
 136
 137 *datasum*::
 138 *nodatasum*::
 139 (default: on)
 140 +
 141 Enable data checksumming for newly created files.
 142 'Datasum' implies 'datacow', ie. the normal mode of operation. All files created
 143 under 'nodatasum' inherit the "no checksums" property, however there's no
 144 corresponding file attribute (see `chattr`(1)).
 145
 146 *degraded*::
 147 (default: off)
 148 +
 149 Allow mounts with less devices than the raid profile constraints
 150 require.  A read-write mount (or remount) may fail with too many devices
 151 missing, for example if a stripe member is completely missing from RAID0.
 152
 153 *device='devicepath'*::
 154 Specify a path to a device that will be scanned for BTRFS filesystem during
 155 mount. This is usually done automatically by a device manager (like udev) or
 156 using the *btrfs device scan* command (eg. run from the initial ramdisk). In
 157 cases where this is not possible the 'device' mount option can help.
 158 +
 159 NOTE: booting eg. a RAID1 system may fail even if all filesystem's 'device'
 160 paths are provided as the actual device nodes may not be discovered by the
 161 system at that point.
 162
 163 *discard*::
 164 *nodiscard*::
 165 (default: off)
 166 +
 167 Enable discarding of freed file blocks using TRIM operation.  This is useful
 168 for SSD devices, thinly provisioned LUNs or virtual machine images where the
 169 backing device understands the operation. Depending on support of the
 170 underlying device, the operation may severely hurt performance in case the TRIM
 171 operation is synchronous (eg. with SATA devices up to revision 3.0).
 172 +
 173 If discarding is not necessary to be done at the block freeing time, there's
 174 *fstrim* tool that lets the filesystem discard all free blocks in a batch,
 175 possibly not much interfering with other operations.
 176
 177 *enospc_debug*::
 178 *noenospc_debug*::
 179 (default: off)
 180 +
 181 Enable verbose output for some ENOSPC conditions. It's safe to use but can
 182 be noisy if the system hits reaches near-full state.
 183
 184 *fatal_errors='action'*::
 185 (since: 3.4, default: bug)
 186 +
 187 Action to take when encountering a fatal error.
 188 +
 189 *bug*::::
 190 'BUG()' on a fatal error, the system will stay in the crashed state and may be
 191 still partially usable, but reboot is required for full operation
 192 +
 193 *panic*::::
 194 'panic()' on a fatal error, depending on other system configuration, this may
 195 be followed by a reboot. Please refer to the documentation of kernel boot
 196 parameters, eg. 'panic', 'oops' or 'crashkernel'.
 197
 198 *flushoncommit*::
 199 *noflushoncommit*::
 200 (default: on)
 201 +
 202 This option forces any data dirtied by a write in a prior transaction to commit
 203 as part of the current commit.  This makes the committed state a fully
 204 consistent view of the file system from the application's perspective (i.e., it
 205 includes all completed file system operations).  This was previously the
 206 behavior only when a snapshot was created.
 207 +
 208 Disabling flushing may improve performance but is not crash-safe.
 209
 210 *fragment='type'*::
 211 (depends on compile-time option BTRFS_DEBUG, since: 4.4, default: off)
 212 +
 213 A debugging helper to intentionally fragment given 'type' of block groups. The
 214 type can be 'data', 'metadata' or 'all'. This mount option should not be used
 215 outside of debugging environments and is not recognized if the kernel config
 216 option 'BTRFS_DEBUG' is not enabled.
 217
 218 *inode_cache*::
 219 *noinode_cache*::
 220 (since: 3.0, default: off)
 221 +
 222 Enable free inode number caching. Not recommended to use unless files on your
 223 filesystem get assigned inode numbers that are approaching 2^64^. Normally, new
 224 files in each subvolume get assigned incrementally (plus one from the last
 225 time) and are not reused. The mount option turns on caching of the existing
 226 inode numbers and reuse of inode numbers of deleted files.
 227 +
 228 This option may slow down your system at first run, or after mounting without
 229 the option.
 230 +
 231 NOTE: Defaults to off due to a potential overflow problem when the free space
 232 checksums don't fit inside a single page.
 233
 234 *max_inline='bytes'*::
 235 (default: min(8192, page size) )
 236 +
 237 Specify the maximum amount of space, in bytes, that can be inlined in
 238 a metadata B-tree leaf.  The value is specified in bytes, optionally
 239 with a K suffix (case insensitive).  In practice, this value
 240 is limited by the filesystem block size (named 'sectorsize' at mkfs time),
 241 and memory page size of the system. In case of sectorsize limit, there's
 242 some space unavailable due to leaf headers.  For example, a 4k sectorsize, max
 243 inline data is ~3900 bytes.
 244 +
 245 Inlining can be completely turned off specifying 0. This will increase data
 246 block slack if file sizes are much smaller than block size but will reduce
 247 metadata consumption in return.
 248
 249 *metadata_ratio='value'*::
 250 (default: 0, internal logic)
 251 +
 252 Specifies that 1 metadata chunk should be allocated after every 'value' data
 253 chunks. Default behaviour depends on internal logic, some percent of unused
 254 metadata space is attempted to be maintained but is not always possible if
 255 there's not space left for chunk allocation. The option could be useful to
 256 override the internal logic in favor of the metadata allocation if the expected
 257 workload is supposed to be metadata intense (snapshots, reflinks, xattrs,
 258 inlined files).
 259
 260 *recovery*::
 261 (since: 3.2, default: off)
 262 +
 263 Enable autorecovery attempts if a bad tree root is found at mount time.
 264 Currently this scans a backup list of several previous tree roots and tries to
 265 use the first readable. This can be used with read-only mounts as well.
 266
 267 *rescan_uuid_tree*::
 268 (since: 3.12, default: off)
 269 +
 270 Force check and rebuild procedure of the UUID tree. This should not
 271 normally be needed.
 272
 273 *skip_balance*::
 274 (since: 3.3, default: off)
 275 +
 276 Skip automatic resume of interrupted balance operation after mount.
 277 May be resumed with *btrfs balance resume* or the paused state can be removed
 278 by *btrfs balance cancel*.
 279
 280 *space_cache*::
 281 *space_cache=v2*::
 282 *nospace_cache*::
 283 ('nospace_cache' since: 3.2, 'space_cache=v2' since 4.5, default: on)
 284 +
 285 Options to control the free space cache.  This affects performance as searching
 286 for new free blocks could take longer if the space cache is not enabled. On the
 287 other hand, managing the space cache consumes some resources.  It can be
 288 disabled without clearing at mount time.
 289 +
 290 There are two implementations of how the space is tracked. The safe default is
 291 'v1'.  On large filesystems (many-terabytes) and certain workloads the 'v1'
 292 performance may degrade.  This problem is addressed by 'v2', that is based on
 293 b-trees, sometimes referred to as 'free-space-tree'.
 294 +
 295 'Compatibility notes:'
 296 +
 297 * the 'v2' has to be enabled manually at mount time, once
 298 * kernel without 'v2' support will be able to mount the filesystem in read-only mode
 299 * 'v2' can be removed by mounting with 'clear_cache'
 300
 301 *ssd*::
 302 *nossd*::
 303 *ssd_spread*::
 304 (default: SSD autodetected)
 305 +
 306 Options to control SSD allocation schemes.  By default, BTRFS will
 307 enable or disable SSD allocation heuristics depending on whether a
 308 rotational or non-rotational disk is in use.  The 'ssd' and 'nossd' options
 309 can override this autodetection.
 310 +
 311 The 'ssd_spread' mount option attempts to allocate into bigger and aligned
 312 chunks of unused space, and may perform better on low-end SSDs.  'ssd_spread'
 313 implies 'ssd', enabling all other SSD heuristics as well.
 314
 315 *subvol='path'*::
 316 Mount subvolume from 'path' rather than the toplevel subvolume. The
 317 'path' is absolute (ie. starts at the toplevel subvolume).
 318 This mount option overrides the default subvolume set for the given filesystem.
 319
 320 *subvolid='subvolid'*::
 321 Mount subvolume specified by a 'subvolid' number rather than the toplevel
 322 subvolume.  You can use *btrfs subvolume list* to see subvolume ID numbers.
 323 This mount option overrides the default subvolume set for the given filesystem.
 324
 325 *subvolrootid='objectid'*::
 326 (irrelevant since: 3.2, formally deprecated since: 3.10)
 327 +
 328 A workaround option from times (pre 3.2) when it was not possible to mount a
 329 subvolume that did not reside directly under the toplevel subvolume.
 330
 331 *thread_pool='number'*::
 332 (default: min(NRCPUS + 2, 8) )
 333 +
 334 The number of worker threads to allocate. NRCPUS is number of on-line CPUs
 335 detected at the time of mount. Small number leads to less parallelism in
 336 processing data and metadata, higher numbers could lead to a performance due to
 337 increased locking contention, cache-line bouncing or costly data transfers
 338 between local CPU memories.
 339
 340 *treelog*::
 341 *notreelog*::
 342 (default: on)
 343 +
 344 Enable the tree logging used for 'fsync' and 'O_SYNC' writes. The tree log
 345 stores changes without the need of a full filesystem sync. The log operations
 346 are flushed at sync and transaction commit. If the system crashes between two
 347 such syncs, the pending tree log operations are replayed during mount.
 348 +
 349 WARNING: currently, the tree log is replayed even with a read-only mount!
 350 +
 351 The tree log could contain new files/directories, these would not exist on
 352 a mounted filesystem if the log is not replayed.
 353
 354 *user_subvol_rm_allowed*::
 355 (default: off)
 356 +
 357 Allow subvolumes to be deleted by their respective owner. Otherwise, only the
 358 root user can do that.
 359
 360 FILE ATTRIBUTES
 361 ---------------
 362 The btrfs filesystem supports setting the following file attributes using the
 363 `chattr`(1) utility:
 364
 365 *a*::
 366 'append only', new writes are always written at the end of the file
 367
 368 *A*::
 369 'no atime updates'
 370
 371 *c*::
 372 'compress data', all data written after this attribute is set will be compressed.
 373 Please note that compression is also affected by the mount options or the parent
 374 directory attributes.
 375 +
 376 When set on a directory, all newly created files will inherit this attribute.
 377
 378 *C*::
 379 'no copy-on-write', file modifications are done in-place
 380 +
 381 When set on a directory, all newly created files will inherit this attribute.
 382 +
 383 NOTE: due to implementation limitations, this flag can be set/unset only on
 384 empty files.
 385
 386 *d*::
 387 'no dump', makes sense with 3rd party tools like `dump`(8), on BTRFS the
 388 attribute can be set/unset on no other special handling is done
 389
 390 *D*::
 391 'synchronous directory updates', for more details search `open`(2) for 'O_SYNC'
 392 and 'O_DSYNC'
 393
 394 *i*::
 395 'immutable', no file data and metadata changes allowed even to the root user as
 396 long as this attribute is set (obviously the exception is unsetting the attribute)
 397
 398 *S*::
 399 'synchronous updates', for more details search `open`(2) for 'O_SYNC' and
 400 'O_DSYNC'
 401
 402 *X*::
 403 'no compression', permanently turn off compression on the given file, other
 404 compression mount options will not affect that
 405 +
 406 When set on a directory, all newly created files will inherit this attribute.
 407
 408 No other attributes are supported.  For the complete list please refer to the
 409 `chattr`(1) manual page.
 410
 411 SEE ALSO
 412 --------
 413 `acl`(5),
 414 `btrfs`(8),
 415 `chattr`(1),
 416 `fstrim`(8),
 417 `mkfs.btrfs`(8),
 418 `mount`(8)