About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / filesystems / btrfs.txt




Custom Search

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
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.