blob: d11cc2f8077b9ea6e4284419fd40121c13d0d1c2 [file] [log] [blame]
David Woodhouse709ac062009-01-07 09:54:24 -05001
Eric Sandeenc854a992013-03-26 19:36:12 +00002BTRFS
3=====
David Woodhouse709ac062009-01-07 09:54:24 -05004
Eric Sandeenc854a992013-03-26 19:36:12 +00005Btrfs is a copy on write filesystem for Linux aimed at
David Woodhouse709ac062009-01-07 09:54:24 -05006implementing advanced features while focusing on fault tolerance,
7repair and easy administration. Initially developed by Oracle, Btrfs
8is licensed under the GPL and open for contribution from anyone.
9
10Linux has a wealth of filesystems to choose from, but we are facing a
11number of challenges with scaling to the large storage subsystems that
12are becoming common in today's data centers. Filesystems need to scale
13in their ability to address and manage large storage, and also in
14their ability to detect, repair and tolerate errors in the data stored
15on disk. Btrfs is under heavy development, and is not suitable for
16any uses other than benchmarking and review. The Btrfs disk format is
17not yet finalized.
18
19The 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
Eric Sandeenc854a992013-03-26 19:36:12 +000037Mount Options
38=============
David Woodhouse709ac062009-01-07 09:54:24 -050039
Eric Sandeenc854a992013-03-26 19:36:12 +000040When mounting a btrfs filesystem, the following option are accepted.
Qu Wenruo842bef52014-01-06 09:58:25 +080041Options with (*) are default options and will not show in the mount options.
Eric Sandeenc854a992013-03-26 19:36:12 +000042
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
Qu Wenruofc0ca9a2014-01-06 09:58:26 +080049 noautodefrag(*)
Eric Sandeenc854a992013-03-26 19:36:12 +000050 autodefrag
Qu Wenruofc0ca9a2014-01-06 09:58:26 +080051 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.
Eric Sandeenc854a992013-03-26 19:36:12 +000055
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
David Sterba906c1762013-11-20 15:05:51 +010075 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
Eric Sandeenc854a992013-03-26 19:36:12 +000081 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
Masanari Iida9ed354b2013-08-20 20:33:17 +090098 can be avoided. Especially useful when trying to mount a multi-device
Eric Sandeenc854a992013-03-26 19:36:12 +000099 setup as root. May be specified multiple times for multiple devices.
100
Qu Wenruoe07a2ad2014-01-06 09:58:27 +0800101 nodiscard(*)
Eric Sandeenc854a992013-03-26 19:36:12 +0000102 discard
Qu Wenruoe07a2ad2014-01-06 09:58:27 +0800103 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
Eric Sandeenc854a992013-03-26 19:36:12 +0000107 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
Qu Wenruo53036292014-01-06 09:58:28 +0800111 noenospc_debug(*)
Eric Sandeenc854a992013-03-26 19:36:12 +0000112 enospc_debug
Qu Wenruo53036292014-01-06 09:58:28 +0800113 Disable/enable debugging option to be more verbose in some ENOSPC conditions.
Eric Sandeenc854a992013-03-26 19:36:12 +0000114
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
Qu Wenruo2c9ee852014-01-06 09:58:29 +0800120 noflushoncommit(*)
Eric Sandeenc854a992013-03-26 19:36:12 +0000121 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 sectorsize, 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
Qu Wenruobd0330a2014-01-06 09:58:30 +0800144 acl(*)
Eric Sandeenc854a992013-03-26 19:36:12 +0000145 noacl
Qu Wenruobd0330a2014-01-06 09:58:30 +0800146 Enable/disable support for Posix Access Control Lists (ACLs). See the
Eric Sandeenc854a992013-03-26 19:36:12 +0000147 acl(5) manual page for more information about ACLs.
148
Qu Wenruo842bef52014-01-06 09:58:25 +0800149 barrier(*)
Eric Sandeenc854a992013-03-26 19:36:12 +0000150 nobarrier
Qu Wenruo842bef52014-01-06 09:58:25 +0800151 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.
Eric Sandeenc854a992013-03-26 19:36:12 +0000156
Qu Wenruoa258af72014-01-06 09:58:31 +0800157 datacow(*)
Eric Sandeenc854a992013-03-26 19:36:12 +0000158 nodatacow
Qu Wenruoa258af72014-01-06 09:58:31 +0800159 Enable/disable data copy-on-write for newly created files.
160 Nodatacow implies nodatasum, and disables all compression.
Eric Sandeenc854a992013-03-26 19:36:12 +0000161
Qu Wenruod3991672014-01-06 09:58:32 +0800162 datasum(*)
Eric Sandeenc854a992013-03-26 19:36:12 +0000163 nodatasum
Qu Wenruod3991672014-01-06 09:58:32 +0800164 Enable/disable data checksumming for newly created files.
165 Datasum implies datacow.
Eric Sandeenc854a992013-03-26 19:36:12 +0000166
Qu Wenruoa88998f2014-01-06 09:58:33 +0800167 treelog(*)
Eric Sandeenc854a992013-03-26 19:36:12 +0000168 notreelog
Qu Wenruoa88998f2014-01-06 09:58:33 +0800169 Enable/disable the tree logging used for fsync and O_SYNC writes.
Eric Sandeenc854a992013-03-26 19:36:12 +0000170
171 recovery
172 Enable autorecovery attempts if a bad tree root is found at mount time.
173 Currently this scans a list of several previous tree roots and tries to
174 use the first readable.
175
David Sterba906c1762013-11-20 15:05:51 +0100176 rescan_uuid_tree
177 Force check and rebuild procedure of the UUID tree. This should not
178 normally be needed.
179
180 skip_balance
Eric Sandeenc854a992013-03-26 19:36:12 +0000181 Skip automatic resume of interrupted balance operation after mount.
182 May be resumed with "btrfs balance resume."
183
184 space_cache (*)
185 Enable the on-disk freespace cache.
186 nospace_cache
187 Disable freespace cache loading without clearing the cache.
188 clear_cache
189 Force clearing and rebuilding of the disk space cache if something
190 has gone wrong.
191
192 ssd
193 nossd
194 ssd_spread
195 Options to control ssd allocation schemes. By default, BTRFS will
196 enable or disable ssd allocation heuristics depending on whether a
197 rotational or nonrotational disk is in use. The ssd and nossd options
198 can override this autodetection.
199
200 The ssd_spread mount option attempts to allocate into big chunks
201 of unused space, and may perform better on low-end ssds. ssd_spread
202 implies ssd, enabling all other ssd heuristics as well.
203
204 subvol=<path>
205 Mount subvolume at <path> rather than the root subvolume. <path> is
206 relative to the top level subvolume.
207
208 subvolid=<ID>
209 Mount subvolume specified by an ID number rather than the root subvolume.
210 This allows mounting of subvolumes which are not in the root of the mounted
211 filesystem.
212 You can use "btrfs subvolume list" to see subvolume ID numbers.
213
214 subvolrootid=<objectid> (deprecated)
215 Mount subvolume specified by <objectid> rather than the root subvolume.
216 This allows mounting of subvolumes which are not in the root of the mounted
217 filesystem.
218 You can use "btrfs subvolume show " to see the object ID for a subvolume.
219
220 thread_pool=<number>
221 The number of worker threads to allocate. The default number is equal
222 to the number of CPUs + 2, or 8, whichever is smaller.
223
224 user_subvol_rm_allowed
225 Allow subvolumes to be deleted by a non-root user. Use with caution.
226
227MAILING LIST
228============
David Woodhouse709ac062009-01-07 09:54:24 -0500229
230There is a Btrfs mailing list hosted on vger.kernel.org. You can
231find details on how to subscribe here:
232
233http://vger.kernel.org/vger-lists.html#linux-btrfs
234
235Mailing list archives are available from gmane:
236
237http://dir.gmane.org/gmane.comp.file-systems.btrfs
238
239
240
Eric Sandeenc854a992013-03-26 19:36:12 +0000241IRC
242===
David Woodhouse709ac062009-01-07 09:54:24 -0500243
244Discussion of Btrfs also occurs on the #btrfs channel of the Freenode
245IRC network.
246
247
248
249 UTILITIES
250 =========
251
252Userspace tools for creating and manipulating Btrfs file systems are
253available from the git repository at the following location:
254
Arnd Hannemannb52f75a2011-11-16 17:35:37 +0100255 http://git.kernel.org/?p=linux/kernel/git/mason/btrfs-progs.git
256 git://git.kernel.org/pub/scm/linux/kernel/git/mason/btrfs-progs.git
David Woodhouse709ac062009-01-07 09:54:24 -0500257
258These include the following tools:
259
David Sterbac7501792013-11-20 15:06:08 +0100260* mkfs.btrfs: create a filesystem
David Woodhouse709ac062009-01-07 09:54:24 -0500261
David Sterbac7501792013-11-20 15:06:08 +0100262* btrfs: a single tool to manage the filesystems, refer to the manpage for more details
David Woodhouse709ac062009-01-07 09:54:24 -0500263
David Sterbac7501792013-11-20 15:06:08 +0100264* 'btrfsck' or 'btrfs check': do a consistency check of the filesystem
David Woodhouse709ac062009-01-07 09:54:24 -0500265
David Sterbac7501792013-11-20 15:06:08 +0100266Other tools for specific tasks:
David Woodhouse709ac062009-01-07 09:54:24 -0500267
David Sterbac7501792013-11-20 15:06:08 +0100268* btrfs-convert: in-place conversion from ext2/3/4 filesystems
David Woodhouse709ac062009-01-07 09:54:24 -0500269
David Sterbac7501792013-11-20 15:06:08 +0100270* btrfs-image: dump filesystem metadata for debugging