Documentation/btrfs-mount.asciidoc

   1 btrfs-mount(5)
   2 ==============
   3
   4 NAME
   5 ----
   6 btrfs-mount - mount options and supported file attributes for the btrfs filesystem
   7
   8 DESCRIPTION
   9 -----------
  10 This document describes mount options specific to the btrfs filesystem.
  11 Other generic mount options are available,and are described in the
  12 `mount`(8) manpage.
  13
  14 MOUNT OPTIONS
  15 -------------
  16 *alloc_start='bytes'*::
  17         Debugging option to force all block allocations above a certain
  18         byte threshold on each block device.  The value is specified in
  19         bytes, optionally with a K, M, or G suffix, case insensitive.
  20         Default is 1MB.
  21
  22 *autodefrag*::
  23 *noautodefrag*::
  24         (since: 3.0, default: off) +
  25         Disable/enable auto defragmentation.
  26         Auto defragmentation detects small random writes into files and queue
  27         them up for the defrag process.  Works best for small files;
  28         Not well suited for large database workloads.
  29
  30 *check_int*::
  31 *check_int_data*::
  32 *check_int_print_mask='value'*::
  33         (since: 3.0, default: off) +
  34         These debugging options control the behavior of the integrity checking
  35         module (the BTRFS_FS_CHECK_INTEGRITY config option required). +
  36         +
  37         `check_int` enables the integrity checker module, which examines all
  38         block write requests to ensure on-disk consistency, at a large
  39         memory and CPU cost. +
  40         +
  41         `check_int_data` includes extent data in the integrity checks, and
  42         implies the check_int option. +
  43         +
  44         `check_int_print_mask` takes a bitmask of BTRFSIC_PRINT_MASK_* values
  45         as defined in 'fs/btrfs/check-integrity.c', to control the integrity
  46         checker module behavior. +
  47         +
  48         See comments at the top of 'fs/btrfs/check-integrity.c'
  49         for more info.
  50
  51 *commit='seconds'*::
  52         (since: 3.12, default: 30) +
  53         Set the interval of periodic commit. Higher
  54         values defer data being synced to permanent storage with obvious
  55         consequences when the system crashes. The upper bound is not forced,
  56         but a warning is printed if it's more than 300 seconds (5 minutes).
  57
  58 *compress*::
  59 *compress='type'*::
  60 *compress-force*::
  61 *compress-force='type'*::
  62         (default: off) +
  63         Control BTRFS file data compression.  Type may be specified as 'zlib',
  64         'lzo' or 'no' (for no compression, used for remounting).  If no type
  65         is specified, 'zlib' is used.  If compress-force is specified,
  66         all files will be compressed, whether or not they compress well.
  67         NOTE: If compression is enabled, 'nodatacow' and 'nodatasum' are disabled.
  68
  69 *degraded*::
  70         (default: off) +
  71         Allow mounts to continue with missing devices.  A read-write mount may
  72         fail with too many devices missing, for example if a stripe member
  73         is completely missing.
  74
  75 *device='devicepath'*::
  76         Specify a device during mount so that ioctls on the control device
  77         can be avoided.  Especially useful when trying to mount a multi-device
  78         setup as root.  May be specified multiple times for multiple devices.
  79
  80 *discard*::
  81 *nodiscard*::
  82         (default: off) +
  83         Disable/enable discard mount option.
  84         Discard issues frequent commands to let the block device reclaim space
  85         freed by the filesystem.
  86         This is useful for SSD devices, thinly provisioned
  87         LUNs and virtual machine images, but may have a significant
  88         performance impact.  (The fstrim command is also available to
  89         initiate batch trims from userspace).
  90
  91 *enospc_debug*::
  92         (default: off) +
  93         Disable/enable debugging option to be more verbose in some ENOSPC conditions.
  94
  95 *fatal_errors='action'*::
  96         (since: 3.4, default: bug) +
  97         Action to take when encountering a fatal error. +
  98                 "bug" - BUG() on a fatal error. +
  99                 "panic" - panic() on a fatal error.
 100
 101 *flushoncommit*::
 102 *noflushoncommit*::
 103         (default: on) +
 104         The `flushoncommit` mount option forces any data dirtied by a write in a
 105         prior transaction to commit as part of the current commit.  This makes
 106         the committed state a fully consistent view of the file system from the
 107         application's perspective (i.e., it includes all completed file system
 108         operations).  This was previously the behavior only when a snapshot is
 109         created.
 110
 111 *inode_cache*::
 112 *noinode_cache*::
 113         (since: 3.0, default: off) +
 114         Enable free inode number caching.   Defaults to off due to an overflow
 115         problem when the free space crcs don't fit inside a single page.
 116
 117 *max_inline='bytes'*::
 118         (default: min(8192, page size) )
 119         Specify the maximum amount of space, in bytes, that can be inlined in
 120         a metadata B-tree leaf.  The value is specified in bytes, optionally
 121         with a K, M, or G suffix, case insensitive.  In practice, this value
 122         is limited by the root sector size, with some space unavailable due
 123         to leaf headers.  For a 4k sectorsize, max inline data is ~3900 bytes.
 124
 125 *metadata_ratio='value'*::
 126         Specify that 1 metadata chunk should be allocated after every
 127         'value' data chunks.  Off by default.
 128
 129 *acl*::
 130 *noacl*::
 131         (default: on) +
 132         Enable/disable support for Posix Access Control Lists (ACLs).  See the
 133         `acl`(5) manual page for more information about ACLs.
 134
 135 *barrier*::
 136 *nobarrier*::
 137         (default: on) +
 138         ensure that certain IOs make it through the device cache and are on
 139         persistent storage. If disabled on a device with a volatile
 140         (non-battery-backed) write-back cache, nobarrier option will lead to
 141         filesystem corruption on a system crash or power loss.
 142
 143 *datacow*::
 144 *nodatacow*::
 145         (default: on) +
 146         Enable/disable data copy-on-write for newly created files.
 147         Nodatacow implies nodatasum, and disables all compression.
 148
 149 *datasum*::
 150 *nodatasum*::
 151         (default: on) +
 152         Enable/disable data checksumming for newly created files.
 153         Datasum implies datacow.
 154
 155 *treelog*::
 156 *notreelog*::
 157         (default: on) +
 158         Enable/disable the tree logging used for fsync and O_SYNC writes.
 159
 160 *recovery*::
 161         (since: 3.2, default: off) +
 162         Enable autorecovery attempts if a bad tree root is found at mount time.
 163         Currently this scans a list of several previous tree roots and tries to
 164         use the first readable.
 165
 166 *rescan_uuid_tree*::
 167         (since: 3.12, default: off) +
 168         Force check and rebuild procedure of the UUID tree. This should not
 169         normally be needed.
 170
 171 *skip_balance*::
 172         (since: 3.3, default: off) +
 173         Skip automatic resume of interrupted balance operation after mount.
 174         May be resumed with "btrfs balance resume."
 175
 176 *nospace_cache*::
 177         (since: 3.2) +
 178         Disable freespace cache loading without clearing the cache.
 179
 180 *clear_cache*::
 181         Force clearing and rebuilding of the disk space cache if something
 182         has gone wrong.
 183
 184 *ssd*::
 185 *nossd*::
 186 *ssd_spread*::
 187         Options to control ssd allocation schemes.  By default, BTRFS will
 188         enable or disable ssd allocation heuristics depending on whether a
 189         rotational or nonrotational disk is in use.  The ssd and nossd options
 190         can override this autodetection. +
 191         The ssd_spread mount option attempts to allocate into big chunks
 192         of unused space, and may perform better on low-end ssds.  ssd_spread
 193         implies ssd, enabling all other ssd heuristics as well.
 194
 195 *subvol='path'*::
 196         Mount subvolume at 'path' rather than the root subvolume. The
 197         'path' is relative to the top level subvolume.
 198
 199 *subvolid='ID'*::
 200         Mount subvolume specified by an ID number rather than the root subvolume.
 201         This allows mounting of subvolumes which are not in the root of the mounted
 202         filesystem.
 203         You can use "btrfs subvolume list" to see subvolume ID numbers.
 204
 205 *subvolrootid='objectid'*::
 206         (deprecated) +
 207         Mount subvolume specified by 'objectid' rather than the root subvolume.
 208         This allows mounting of subvolumes which are not in the root of the mounted
 209         filesystem.
 210         You can use "btrfs subvolume show" to see the object ID for a subvolume.
 211
 212 *thread_pool='number'*::
 213         The number of worker threads to allocate.  The default number is equal
 214         to the number of CPUs + 2, or 8, whichever is smaller.
 215
 216 *user_subvol_rm_allowed*::
 217         (default: off) +
 218         Allow subvolumes to be deleted by a non-root user. Use with caution.
 219
 220 FILE ATTRIBUTES
 221 ---------------
 222 The btrfs filesystem supports setting the following file
 223 attributes the `chattr`(1) utility
 224
 225 *a* -- append only
 226
 227 *A* -- no atime updates
 228
 229 *c* -- compressed
 230
 231 *C* -- no copy on write
 232
 233 *d* -- no dump
 234
 235 *D* -- synchronous directory updates
 236
 237 *i* -- immutable
 238
 239 *S* -- synchronous updates
 240
 241 *X* -- no compression
 242
 243 For descriptions of these attribute flags, please refer to the
 244 `chattr`(1) man page.
 245
 246 SEE ALSO
 247 --------
 248 `chattr`(1),
 249 `mkfs.btrfs`(8),
 250 `mount`(8),
 251 `btrfs`(8)