Based on kernel version 3.13. Page generated on 2014-01-20 22:02 EST.
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 Unless otherwise specified, all options default to off. 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 autodefrag 50 Detect small random writes into files and queue them up for the 51 defrag process. Works best for small files; Not well suited for 52 large database workloads. 53 54 check_int 55 check_int_data 56 check_int_print_mask=<value> 57 These debugging options control the behavior of the integrity checking 58 module (the BTRFS_FS_CHECK_INTEGRITY config option required). 59 60 check_int enables the integrity checker module, which examines all 61 block write requests to ensure on-disk consistency, at a large 62 memory and CPU cost. 63 64 check_int_data includes extent data in the integrity checks, and 65 implies the check_int option. 66 67 check_int_print_mask takes a bitmask of BTRFSIC_PRINT_MASK_* values 68 as defined in fs/btrfs/check-integrity.c, to control the integrity 69 checker module behavior. 70 71 See comments at the top of fs/btrfs/check-integrity.c for more info. 72 73 commit=<seconds> 74 Set the interval of periodic commit, 30 seconds by default. Higher 75 values defer data being synced to permanent storage with obvious 76 consequences when the system crashes. The upper bound is not forced, 77 but a warning is printed if it's more than 300 seconds (5 minutes). 78 79 compress 80 compress=<type> 81 compress-force 82 compress-force=<type> 83 Control BTRFS file data compression. Type may be specified as "zlib" 84 "lzo" or "no" (for no compression, used for remounting). If no type 85 is specified, zlib is used. If compress-force is specified, 86 all files will be compressed, whether or not they compress well. 87 If compression is enabled, nodatacow and nodatasum are disabled. 88 89 degraded 90 Allow mounts to continue with missing devices. A read-write mount may 91 fail with too many devices missing, for example if a stripe member 92 is completely missing. 93 94 device=<devicepath> 95 Specify a device during mount so that ioctls on the control device 96 can be avoided. Especially useful when trying to mount a multi-device 97 setup as root. May be specified multiple times for multiple devices. 98 99 discard 100 Issue frequent commands to let the block device reclaim space freed by 101 the filesystem. This is useful for SSD devices, thinly provisioned 102 LUNs and virtual machine images, but may have a significant 103 performance impact. (The fstrim command is also available to 104 initiate batch trims from userspace). 105 106 enospc_debug 107 Debugging option to be more verbose in some ENOSPC conditions. 108 109 fatal_errors=<action> 110 Action to take when encountering a fatal error: 111 "bug" - BUG() on a fatal error. This is the default. 112 "panic" - panic() on a fatal error. 113 114 flushoncommit 115 The 'flushoncommit' mount option forces any data dirtied by a write in a 116 prior transaction to commit as part of the current commit. This makes 117 the committed state a fully consistent view of the file system from the 118 application's perspective (i.e., it includes all completed file system 119 operations). This was previously the behavior only when a snapshot is 120 created. 121 122 inode_cache 123 Enable free inode number caching. Defaults to off due to an overflow 124 problem when the free space crcs don't fit inside a single page. 125 126 max_inline=<bytes> 127 Specify the maximum amount of space, in bytes, that can be inlined in 128 a metadata B-tree leaf. The value is specified in bytes, optionally 129 with a K, M, or G suffix, case insensitive. In practice, this value 130 is limited by the root sector size, with some space unavailable due 131 to leaf headers. For a 4k sectorsize, max inline data is ~3900 bytes. 132 133 metadata_ratio=<value> 134 Specify that 1 metadata chunk should be allocated after every <value> 135 data chunks. Off by default. 136 137 noacl 138 Disable support for Posix Access Control Lists (ACLs). See the 139 acl(5) manual page for more information about ACLs. 140 141 nobarrier 142 Disables the use of block layer write barriers. Write barriers ensure 143 that certain IOs make it through the device cache and are on persistent 144 storage. If used on a device with a volatile (non-battery-backed) 145 write-back cache, this option will lead to filesystem corruption on a 146 system crash or power loss. 147 148 nodatacow 149 Disable data copy-on-write for newly created files. Implies nodatasum, 150 and disables all compression. 151 152 nodatasum 153 Disable data checksumming for newly created files. 154 155 notreelog 156 Disable the tree logging used for fsync and O_SYNC writes. 157 158 recovery 159 Enable autorecovery attempts if a bad tree root is found at mount time. 160 Currently this scans a list of several previous tree roots and tries to 161 use the first readable. 162 163 rescan_uuid_tree 164 Force check and rebuild procedure of the UUID tree. This should not 165 normally be needed. 166 167 skip_balance 168 Skip automatic resume of interrupted balance operation after mount. 169 May be resumed with "btrfs balance resume." 170 171 space_cache (*) 172 Enable the on-disk freespace cache. 173 nospace_cache 174 Disable freespace cache loading without clearing the cache. 175 clear_cache 176 Force clearing and rebuilding of the disk space cache if something 177 has gone wrong. 178 179 ssd 180 nossd 181 ssd_spread 182 Options to control ssd allocation schemes. By default, BTRFS will 183 enable or disable ssd allocation heuristics depending on whether a 184 rotational or nonrotational disk is in use. The ssd and nossd options 185 can override this autodetection. 186 187 The ssd_spread mount option attempts to allocate into big chunks 188 of unused space, and may perform better on low-end ssds. ssd_spread 189 implies ssd, enabling all other ssd heuristics as well. 190 191 subvol=<path> 192 Mount subvolume at <path> rather than the root subvolume. <path> is 193 relative to the top level subvolume. 194 195 subvolid=<ID> 196 Mount subvolume specified by an ID number rather than the root subvolume. 197 This allows mounting of subvolumes which are not in the root of the mounted 198 filesystem. 199 You can use "btrfs subvolume list" to see subvolume ID numbers. 200 201 subvolrootid=<objectid> (deprecated) 202 Mount subvolume specified by <objectid> rather than the root subvolume. 203 This allows mounting of subvolumes which are not in the root of the mounted 204 filesystem. 205 You can use "btrfs subvolume show " to see the object ID for a subvolume. 206 207 thread_pool=<number> 208 The number of worker threads to allocate. The default number is equal 209 to the number of CPUs + 2, or 8, whichever is smaller. 210 211 user_subvol_rm_allowed 212 Allow subvolumes to be deleted by a non-root user. Use with caution. 213 214 MAILING LIST 215 ============ 216 217 There is a Btrfs mailing list hosted on vger.kernel.org. You can 218 find details on how to subscribe here: 219 220 http://vger.kernel.org/vger-lists.html#linux-btrfs 221 222 Mailing list archives are available from gmane: 223 224 http://dir.gmane.org/gmane.comp.file-systems.btrfs 225 226 227 228 IRC 229 === 230 231 Discussion of Btrfs also occurs on the #btrfs channel of the Freenode 232 IRC network. 233 234 235 236 UTILITIES 237 ========= 238 239 Userspace tools for creating and manipulating Btrfs file systems are 240 available from the git repository at the following location: 241 242 http://git.kernel.org/?p=linux/kernel/git/mason/btrfs-progs.git 243 git://git.kernel.org/pub/scm/linux/kernel/git/mason/btrfs-progs.git 244 245 These include the following tools: 246 247 * mkfs.btrfs: create a filesystem 248 249 * btrfs: a single tool to manage the filesystems, refer to the manpage for more details 250 251 * 'btrfsck' or 'btrfs check': do a consistency check of the filesystem 252 253 Other tools for specific tasks: 254 255 * btrfs-convert: in-place conversion from ext2/3/4 filesystems 256 257 * btrfs-image: dump filesystem metadata for debugging