Documentation/btrfs-mount.txt

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