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 not practial 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 unwrittent 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 severly 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 *inode_cache*::
 211 *noinode_cache*::
 212 (since: 3.0, default: off)
 213 +
 214 Enable free inode number caching. Not recommended to use unless files on your
 215 filesystem get assigned inode numbers that are approaching 2^64^. Normally, new
 216 files in each subvolume get assigned incrementally (plus one from the last
 217 time) and are not reused. The mount option turns on caching of the existing
 218 inode numbers and reuse of inode numbers of deleted files.
 219 +
 220 This option may slow down your system at first run, or after mounting without
 221 the option.
 222 +
 223 NOTE: Defaults to off due to a potential overflow problem when the free space
 224 checksums don't fit inside a single page.
 225
 226 *max_inline='bytes'*::
 227 (default: min(8192, page size) )
 228 +
 229 Specify the maximum amount of space, in bytes, that can be inlined in
 230 a metadata B-tree leaf.  The value is specified in bytes, optionally
 231 with a K suffix (case insensitive).  In practice, this value
 232 is limited by the filesystem block size (named 'sectorsize' at mkfs time),
 233 and memory page size of the system. In case of sectorsize limit, there's
 234 some space unavailable due to leaf headers.  For example, a 4k sectorsize, max
 235 inline data is ~3900 bytes.
 236 +
 237 Inlining can be completely turned off specifying 0. This will increase data
 238 block slack if file sizes are much smaller than block size but will reduce
 239 metadata consumption in return.
 240
 241 *metadata_ratio='value'*::
 242 (default: 0, internal logic)
 243 +
 244 Specifies that 1 metadata chunk should be allocated after every 'value' data
 245 chunks. Default behaviour depends on internal logic, some percent of unused
 246 metadata space is attempted to be maintained but is not always possible if
 247 there's not space left for chunk allocation. The option could be useful to
 248 override the internal logic in favor of the metadata allocation if the expected
 249 workload is supposed to be metadata intense (snapshots, reflinks, xattrs,
 250 inlined files).
 251
 252 *recovery*::
 253 (since: 3.2, default: off)
 254 +
 255 Enable autorecovery attempts if a bad tree root is found at mount time.
 256 Currently this scans a backup list of several previous tree roots and tries to
 257 use the first readable. This can be used with read-only mounts as well.
 258
 259 *rescan_uuid_tree*::
 260 (since: 3.12, default: off)
 261 +
 262 Force check and rebuild procedure of the UUID tree. This should not
 263 normally be needed.
 264
 265 *skip_balance*::
 266 (since: 3.3, default: off)
 267 +
 268 Skip automatic resume of interrupted balance operation after mount.
 269 May be resumed with *btrfs balance resume* or the paused state can be removed
 270 by *btrfs balance cancel*.
 271
 272 *space_cache*::
 273 *nospace_cache*::
 274 ('nospace_cache' since: 3.2, default: on)
 275 +
 276 Disable freespace cache loading without clearing the cache and the free space
 277 cache will not be used during the mount. This affects performance as searching
 278 for new free blocks could take longer. On the other hand, managing the space
 279 cache consumes some resources.
 280
 281 *ssd*::
 282 *nossd*::
 283 *ssd_spread*::
 284 (default: SSD autodetected)
 285 +
 286 Options to control SSD allocation schemes.  By default, BTRFS will
 287 enable or disable SSD allocation heuristics depending on whether a
 288 rotational or nonrotational disk is in use.  The 'ssd' and 'nossd' options
 289 can override this autodetection.
 290 +
 291 The 'ssd_spread' mount option attempts to allocate into bigger and aligned
 292 chunks of unused space, and may perform better on low-end SSDs.  'ssd_spread'
 293 implies 'ssd', enabling all other SSD heuristics as well.
 294
 295 *subvol='path'*::
 296 Mount subvolume from 'path' rather than the toplevel subvolume. The
 297 'path' is absolute (ie. starts at the toplevel subvolume).
 298 This mount option overrides the default subvolume set for the given filesystem.
 299
 300 *subvolid='subvolid'*::
 301 Mount subvolume specified by a 'subvolid' number rather than the toplevel
 302 subvolume.  You can use *btrfs subvolume list* to see subvolume ID numbers.
 303 This mount option overrides the default subvolume set for the given filesystem.
 304
 305 *subvolrootid='objectid'*::
 306 (irrelevant since: 3.2, formally deprecated since: 3.10)
 307 +
 308 A workaround option from times (pre 3.2) when it was not possible to mount a
 309 subvolume that did not reside directly under the toplevel subvolume.
 310
 311 *thread_pool='number'*::
 312 (default: min(NRCPUS + 2, 8) )
 313 +
 314 The number of worker threads to allocate. NRCPUS is number of on-line CPUs
 315 detected at the time of mount. Small number leads to less parallelism in
 316 processing data and metadata, higher numbers could lead to a performance due to
 317 increased locking contention, cache-line bouncing or costly data transfers
 318 between local CPU memories.
 319
 320 *treelog*::
 321 *notreelog*::
 322 (default: on)
 323 +
 324 Enable the tree logging used for 'fsync' and 'O_SYNC' writes. The tree log
 325 stores changes without the need of a full filesystem sync. The log operations
 326 are flushed at sync and transaction commit. If the system crashes between two
 327 such syncs, the pending tree log operations are replayed during mount.
 328 +
 329 WARNING: currently, the tree log is replayed even with a read-only mount!
 330 +
 331 The tree log could contain new files/directories, these would not exist on
 332 a mounted filesystm if the log is not replayed.
 333
 334 *user_subvol_rm_allowed*::
 335 (default: off)
 336 +
 337 Allow subvolumes to be deleted by their respective owner. Otherwise, only the
 338 root user can do that.
 339
 340 FILE ATTRIBUTES
 341 ---------------
 342 The btrfs filesystem supports setting the following file attributes using the
 343 `chattr`(1) utility:
 344
 345 *a*::
 346 'append only', new writes are always written at the end of the file
 347
 348 *A*::
 349 'no atime updates'
 350
 351 *c*::
 352 'compress data', all data written after this attribute is set will be compressed.
 353 Please note that compression is also affected by the mount options or the parent
 354 directory attributes.
 355 +
 356 When set on a directory, all newly created files will inherit this attribute.
 357
 358 *C*::
 359 'no copy-on-write', file modifications are done in-place
 360 +
 361 When set on a directory, all newly created files will inherit this attribute.
 362 +
 363 NOTE: due to implementation limitations, this flag can be set/unset only on
 364 empty files.
 365
 366 *d*::
 367 'no dump', makes sense with 3rd party tools like `dump`(8), on BTRFS the
 368 attribute can be set/unset on no other special handling is done
 369
 370 *D*::
 371 'synchronous directory updates', for more details search `open`(2) for 'O_SYNC'
 372 and 'O_DSYNC'
 373
 374 *i*::
 375 'immutable', no file data and metadata changes allowed even to the root user as
 376 long as this attribute is set (obviously the exception is unsetting the attribute)
 377
 378 *S*::
 379 'synchronous updates', for more details search `open`(2) for 'O_SYNC' and
 380 'O_DSYNC'
 381
 382 *X*::
 383 'no compression', permanently turn off compression on the given file, other
 384 compression mount options will not affect that
 385 +
 386 When set on a directory, all newly created files will inherit this attribute.
 387
 388 No other attributes are supported.  For the complete list please refer to the
 389 `chattr`(1) manual page.
 390
 391 SEE ALSO
 392 --------
 393 `acl`(5),
 394 `btrfs`(8),
 395 `chattr`(1),
 396 `fstrim`(8),
 397 `mkfs.btrfs`(8),
 398 `mount`(8)