Documentation/filesystems/btrfs.txt

   1
   2 BTRFS
   3 =====
   4
   5 Btrfs is a copy on write filesystem for Linux aimed at
   6 implementing advanced features while focusing on fault tolerance,
   7 repair and easy administration. Initially developed by Oracle, Btrfs
   8 is licensed under the GPL and open for contribution from anyone.
   9
  10 Linux has a wealth of filesystems to choose from, but we are facing a
  11 number of challenges with scaling to the large storage subsystems that
  12 are becoming common in today's data centers. Filesystems need to scale
  13 in their ability to address and manage large storage, and also in
  14 their ability to detect, repair and tolerate errors in the data stored
  15 on disk.  Btrfs is under heavy development, and is not suitable for
  16 any uses other than benchmarking and review. The Btrfs disk format is
  17 not yet finalized.
  18
  19 The main Btrfs features include:
  20
  21     * Extent based file storage (2^64 max file size)
  22     * Space efficient packing of small files
  23     * Space efficient indexed directories
  24     * Dynamic inode allocation
  25     * Writable snapshots
  26     * Subvolumes (separate internal filesystem roots)
  27     * Object level mirroring and striping
  28     * Checksums on data and metadata (multiple algorithms available)
  29     * Compression
  30     * Integrated multiple device support, with several raid algorithms
  31     * Online filesystem check (not yet implemented)
  32     * Very fast offline filesystem check
  33     * Efficient incremental backup and FS mirroring (not yet implemented)
  34     * Online filesystem defragmentation
  35
  36
  37 Mount Options
  38 =============
  39
  40 When mounting a btrfs filesystem, the following option are accepted.
  41 Options with (*) are default options and will not show in the mount options.
  42
  43   alloc_start=<bytes>
  44         Debugging option to force all block allocations above a certain
  45         byte threshold on each block device.  The value is specified in
  46         bytes, optionally with a K, M, or G suffix, case insensitive.
  47         Default is 1MB.
  48
  49   noautodefrag(*)
  50   autodefrag
  51         Disable/enable auto defragmentation.
  52         Auto defragmentation detects small random writes into files and queue
  53         them up for the defrag process.  Works best for small files;
  54         Not well suited for large database workloads.
  55
  56   check_int
  57   check_int_data
  58   check_int_print_mask=<value>
  59         These debugging options control the behavior of the integrity checking
  60         module (the BTRFS_FS_CHECK_INTEGRITY config option required).
  61
  62         check_int enables the integrity checker module, which examines all
  63         block write requests to ensure on-disk consistency, at a large
  64         memory and CPU cost.
  65
  66         check_int_data includes extent data in the integrity checks, and
  67         implies the check_int option.
  68
  69         check_int_print_mask takes a bitmask of BTRFSIC_PRINT_MASK_* values
  70         as defined in fs/btrfs/check-integrity.c, to control the integrity
  71         checker module behavior.
  72
  73         See comments at the top of fs/btrfs/check-integrity.c for more info.
  74
  75   commit=<seconds>
  76         Set the interval of periodic commit, 30 seconds by default. Higher
  77         values defer data being synced to permanent storage with obvious
  78         consequences when the system crashes. The upper bound is not forced,
  79         but a warning is printed if it's more than 300 seconds (5 minutes).
  80
  81   compress
  82   compress=<type>
  83   compress-force
  84   compress-force=<type>
  85         Control BTRFS file data compression.  Type may be specified as "zlib"
  86         "lzo" or "no" (for no compression, used for remounting).  If no type
  87         is specified, zlib is used.  If compress-force is specified,
  88         all files will be compressed, whether or not they compress well.
  89         If compression is enabled, nodatacow and nodatasum are disabled.
  90
  91   degraded
  92         Allow mounts to continue with missing devices.  A read-write mount may
  93         fail with too many devices missing, for example if a stripe member
  94         is completely missing.
  95
  96   device=<devicepath>
  97         Specify a device during mount so that ioctls on the control device
  98         can be avoided.  Especially useful when trying to mount a multi-device
  99         setup as root.  May be specified multiple times for multiple devices.
 100
 101   nodiscard(*)
 102   discard
 103         Disable/enable discard mount option.
 104         Discard issues frequent commands to let the block device reclaim space
 105         freed by the filesystem.
 106         This is useful for SSD devices, thinly provisioned
 107         LUNs and virtual machine images, but may have a significant
 108         performance impact.  (The fstrim command is also available to
 109         initiate batch trims from userspace).
 110
 111   noenospc_debug(*)
 112   enospc_debug
 113         Disable/enable debugging option to be more verbose in some ENOSPC conditions.
 114
 115   fatal_errors=<action>
 116         Action to take when encountering a fatal error:
 117           "bug" - BUG() on a fatal error.  This is the default.
 118           "panic" - panic() on a fatal error.
 119
 120   noflushoncommit(*)
 121   flushoncommit
 122         The 'flushoncommit' mount option forces any data dirtied by a write in a
 123         prior transaction to commit as part of the current commit.  This makes
 124         the committed state a fully consistent view of the file system from the
 125         application's perspective (i.e., it includes all completed file system
 126         operations).  This was previously the behavior only when a snapshot is
 127         created.
 128
 129   inode_cache
 130         Enable free inode number caching.   Defaults to off due to an overflow
 131         problem when the free space crcs don't fit inside a single page.
 132
 133   max_inline=<bytes>
 134         Specify the maximum amount of space, in bytes, that can be inlined in
 135         a metadata B-tree leaf.  The value is specified in bytes, optionally
 136         with a K, M, or G suffix, case insensitive.  In practice, this value
 137         is limited by the root sector size, with some space unavailable due
 138         to leaf headers.  For a 4k sector size, max inline data is ~3900 bytes.
 139
 140   metadata_ratio=<value>
 141         Specify that 1 metadata chunk should be allocated after every <value>
 142         data chunks.  Off by default.
 143
 144   acl(*)
 145   noacl
 146         Enable/disable support for Posix Access Control Lists (ACLs).  See the
 147         acl(5) manual page for more information about ACLs.
 148
 149   barrier(*)
 150   nobarrier
 151         Enable/disable the use of block layer write barriers.  Write barriers
 152         ensure that certain IOs make it through the device cache and are on
 153         persistent storage. If disabled on a device with a volatile
 154         (non-battery-backed) write-back cache, nobarrier option will lead to
 155         filesystem corruption on a system crash or power loss.
 156
 157   datacow(*)
 158   nodatacow
 159         Enable/disable data copy-on-write for newly created files.
 160         Nodatacow implies nodatasum, and disables all compression.
 161
 162   datasum(*)
 163   nodatasum
 164         Enable/disable data checksumming for newly created files.
 165         Datasum implies datacow.
 166
 167   treelog(*)
 168   notreelog
 169         Enable/disable the tree logging used for fsync and O_SYNC writes.
 170
 171   nologreplay
 172         Disable the log tree replay at mount time to prevent filesystem
 173         from getting modified.
 174         Must be used with 'ro' mount option.
 175         A filesystem mounted with this option cannot transition to a
 176         read-write mount via remount,rw - the filesystem must be unmounted
 177         and mounted back again if read-write access is desired.
 178
 179   usebackuproot
 180         Enable attempts to use backup tree roots if a bad tree root is found at
 181         mount time.
 182         Currently this scans a list of 4 previous tree roots and tries to
 183         use the first readable.
 184         And since the mount option doesn't affect any behavior after mount,
 185         it won't be shown in mount info.
 186         Prior to 4.6, this was done by 'recovery' option that has been
 187         deprecated, but will work.
 188
 189   rescan_uuid_tree
 190         Force check and rebuild procedure of the UUID tree. This should not
 191         normally be needed.
 192
 193   skip_balance
 194         Skip automatic resume of interrupted balance operation after mount.
 195         May be resumed with "btrfs balance resume."
 196
 197   space_cache (*)
 198         Enable the on-disk freespace cache.
 199   nospace_cache
 200         Disable freespace cache loading without clearing the cache.
 201   clear_cache
 202         Force clearing and rebuilding of the disk space cache if something
 203         has gone wrong.
 204
 205   ssd
 206   nossd
 207   ssd_spread
 208         Options to control ssd allocation schemes.  By default, BTRFS will
 209         enable or disable ssd allocation heuristics depending on whether a
 210         rotational or non-rotational disk is in use.  The ssd and nossd options
 211         can override this autodetection.
 212
 213         The ssd_spread mount option attempts to allocate into big chunks
 214         of unused space, and may perform better on low-end ssds.  ssd_spread
 215         implies ssd, enabling all other ssd heuristics as well.
 216
 217   subvol=<path>
 218         Mount subvolume at <path> rather than the root subvolume.  <path> is
 219         relative to the top level subvolume.
 220
 221   subvolid=<ID>
 222         Mount subvolume specified by an ID number rather than the root subvolume.
 223         This allows mounting of subvolumes which are not in the root of the mounted
 224         filesystem.
 225         You can use "btrfs subvolume list" to see subvolume ID numbers.
 226
 227   subvolrootid=<objectid> (deprecated)
 228         Mount subvolume specified by <objectid> rather than the root subvolume.
 229         This allows mounting of subvolumes which are not in the root of the mounted
 230         filesystem.
 231         You can use "btrfs subvolume show " to see the object ID for a subvolume.
 232
 233   thread_pool=<number>
 234         The number of worker threads to allocate.  The default number is equal
 235         to the number of CPUs + 2, or 8, whichever is smaller.
 236
 237   user_subvol_rm_allowed
 238         Allow subvolumes to be deleted by a non-root user. Use with caution.
 239
 240 MAILING LIST
 241 ============
 242
 243 There is a Btrfs mailing list hosted on vger.kernel.org. You can
 244 find details on how to subscribe here:
 245
 246 http://vger.kernel.org/vger-lists.html#linux-btrfs
 247
 248 Mailing list archives are available from gmane:
 249
 250 http://dir.gmane.org/gmane.comp.file-systems.btrfs
 251
 252
 253
 254 IRC
 255 ===
 256
 257 Discussion of Btrfs also occurs on the #btrfs channel of the Freenode
 258 IRC network.
 259
 260
 261
 262         UTILITIES
 263         =========
 264
 265 Userspace tools for creating and manipulating Btrfs file systems are
 266 available from the git repository at the following location:
 267
 268  http://git.kernel.org/?p=linux/kernel/git/mason/btrfs-progs.git
 269  git://git.kernel.org/pub/scm/linux/kernel/git/mason/btrfs-progs.git
 270
 271 These include the following tools:
 272
 273 * mkfs.btrfs: create a filesystem
 274
 275 * btrfs: a single tool to manage the filesystems, refer to the manpage for more details
 276
 277 * 'btrfsck' or 'btrfs check': do a consistency check of the filesystem
 278
 279 Other tools for specific tasks:
 280
 281 * btrfs-convert: in-place conversion from ext2/3/4 filesystems
 282
 283 * btrfs-image: dump filesystem metadata for debugging