Difference between revisions of "Btrfs"

From ArchWiki
Jump to: navigation, search
m (Partitioning: Minor change on commas to periods.)
(Multi-device file system: add some clarifications)
 
(351 intermediate revisions by 69 users not shown)
Line 2: Line 2:
 
[[ja:Btrfs]]
 
[[ja:Btrfs]]
 
[[zh-CN:Btrfs]]
 
[[zh-CN:Btrfs]]
{{Article summary start}}
+
{{Related articles start}}
{{Article summary text|Provides an overview and setup of Btrfs on Arch Linux.}}
+
{{Related|File systems}}
{{Article summary heading|Related}}
+
{{Related|Btrfs - Tips and tricks}}
{{Article summary wiki|Installing on Btrfs root}}
+
{{Related|Mkinitcpio-btrfs}}
{{Article summary wiki|Btrfs - Tips and tricks}}
+
{{Related|Snapper}}
{{Article summary end}}
+
{{Related|dm-crypt/Encrypting an entire system#Btrfs subvolumes with swap}}
 +
{{Related articles end}}
  
Btrfs is an abbreviation for ''B-tree file system'' and is also known as ''Butter FS'' or ''Better FS''.  Btrfs is a copy-on-write (COW) file system written from the ground up for Linux. It is aimed at implementing advanced features while focusing on fault tolerance, repair and easy administration. Jointly developed by Oracle, Red Hat, Fujitsu, Intel, SUSE and many others, Btrfs is licensed under the GPL and open for contribution from anyone.
+
From [[Wikipedia:Btrfs]]:
  
== Installation ==
+
:Btrfs (B-tree file system, pronounced as "butter F S", "better F S", "b-tree F S", or simply by spelling it out) is a file system based on the copy-on-write (COW) principle, initially designed at Oracle Corporation for use in Linux. The development of Btrfs began in 2007, and by August 2014, the file system's on-disk format has been marked as stable.
  
Btrfs is included in the default kernel and its tools ({{Pkg|btrfs-progs}}) are available in the official repositories. [[GRUB]], [[mkinitcpio]], and [[Syslinux]] have support for Btrfs and require no additional configuration.
+
From [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs Wiki]:
  
* On 2012-03-28, {{Pkg|btrfs-progs}} includes ''btrfsck'', a tool that can fix errors on Btrfs filesystems.
+
:Btrfs is a new copy on write (CoW) filesystem for Linux aimed at implementing advanced features while focusing on fault tolerance, repair and easy administration. Jointly developed at Oracle, Red Hat, Fujitsu, Intel, SUSE, STRATO and many others, Btrfs is licensed under the GPL and open for contribution from anyone.
* {{AUR|mkinitcpio-btrfs}}: for roll-back abilities (currently unmaintained).
+
  
{{Note|It is recommended that users use the most up-to-date version of of userspace utils as possible. Consider using {{AUR|btrfs-progs-git}} from the AUR and remember to rebuild it periodically or consider pulling btrfs-progs from the testing repo at a minimum.}}
+
{{Warning|
 +
* Btrfs has some features that are considered experimental. See the Btrfs Wiki's [https://btrfs.wiki.kernel.org/index.php/Main_Page#Stability_status Stability status], [https://btrfs.wiki.kernel.org/index.php/FAQ#Is_btrfs_stable.3F Is Btrfs stable?] and [https://btrfs.wiki.kernel.org/index.php/Getting_started Getting started] for more detailed information.
 +
* Beware of the [[#Limitations|limitations]].
 +
}}
  
== General administration of BTRFS ==
+
== Preparation ==
  
=== Creating a new file system ===
+
The official kernels {{Pkg|linux}} and {{Pkg|linux-lts}} include support for Btrfs. Additionally [[GRUB]], [[mkinitcpio]], and [[Syslinux]] have support for Btrfs and require no additional configuration.
 +
 
 +
User space utilities are available by [[installing]] the {{Pkg|btrfs-progs}} package.
 +
 
 +
== Partitioning ==
 +
 
 +
{{Accuracy|[[Grub#Install_to_partition_or_partitionless_disk]] warns against using it on a partitionless disk.}}
 +
 
 +
Btrfs can occupy an entire data storage device, replacing the [[MBR]] or [[GPT]] partitioning schemes; however, this is not required to simply [[#Creating a new file system|create a Btrfs filesystem]] on an existing [[partition]] that was created using another method. If using Btrfs for partitioning, one can use [[#Subvolumes|subvolumes]] to simulate partitions.
 +
There are some limitations to this approach in single disk setups:
 +
 
 +
* Cannot use different [[file systems]] for different [[fstab|mount points]].
 +
* Cannot use [[Swap|swap area]] as Btrfs does not support [[Swap#Swap_file|swap files]] and there is no place to create [[Swap#Swap_partition|swap partition]]. This also limits the use of hibernation/resume, which needs a swap area to store the hibernation image.
 +
* Cannot use [[UEFI]] to boot.
 +
 
 +
To overwrite the existing partition table with Btrfs, run the following command:
 +
 
 +
# mkfs.btrfs /dev/sd''X''
 +
 
 +
For example, use {{ic|/dev/sda}} rather than {{ic|/dev/sda1}}. The latter would format an existing partition instead of replacing the entire partitioning scheme.
 +
 
 +
Install the [[boot loader]] like you would for a data storage device with a [[Master Boot Record]]. For example, in the case of [[GRUB#Install_to_440-byte_MBR_boot_code_region|GRUB]]:
 +
 
 +
# grub-install --recheck /dev/sd''X''
 +
 
 +
== File system creation ==
  
 
A Btrfs file system can either be newly created or have one converted.
 
A Btrfs file system can either be newly created or have one converted.
 +
 +
=== Creating a new file system ===
 +
 +
==== File system on a single device ====
  
 
To format a partition do:
 
To format a partition do:
Line 30: Line 62:
 
  # mkfs.btrfs -L ''mylabel'' /dev/''partition''
 
  # mkfs.btrfs -L ''mylabel'' /dev/''partition''
  
{{Note|1=As [https://git.kernel.org/cgit/linux/kernel/git/mason/btrfs-progs.git/commit/?id=c652e4efb8e2dd76ef1627d8cd649c6af5905902 this] commit (November 2013), Btrfs default blocksize is 16KB.}}
+
The Btrfs default blocksize is 16KB. To use a larger blocksize for data/metadata, specify a value for the {{ic|nodesize}} via the {{ic|-n}} switch as shown in this example using 16KB blocks:
  
To use a larger blocksize for data/meta data, specify a value for the leafsize via the {{ic|-l}} switch as shown in this example using 16KB blocks:
+
# mkfs.btrfs -L ''mylabel'' -n 16k /dev/''partition''
  
#  mkfs.btrfs -L ''mylabel'' -l 16k /dev/''partition''
+
==== Multi-device file system ====
  
Multiple devices can be entered to create a RAID. Supported RAID levels include RAID 0, RAID 1 and RAID 10. By default the metadata is mirrored and data is striped.
+
Multiple devices can be entered to create a RAID. Supported RAID levels include RAID 0, RAID 1, RAID 10, RAID 5 and RAID 6. The RAID levels can be configured separately for data and metadata using the {{ic|-d}} and {{ic|-m}} options respectively. By default the data is striped ({{ic|raid0}}) and the metadata is mirrored ({{ic|raid1}}). See [https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices Using Btrfs with Multiple Devices] for more information about how to create a Btrfs RAID volume as well as the manpage for {{ic|mkfs.btrfs}}.
  
  # mkfs.btrfs [''options''] /dev/''part1'' /dev/''part2''
+
  # mkfs.btrfs -d raid0 -m raid1 /dev/''part1'' /dev/''part2'' ...
  
=== Convert from Ext3/4 ===
+
{{Note|Mounting such a filesystem may result in all but one of the according ''.device''-jobs getting stuck and systemd never finishing startup due to a [https://github.com/systemd/systemd/issues/1921 bug] in handling this type of filesystem.}}
 +
 
 +
See [[#RAID|RAID]] for advice on maintenance specific to multi-device Btrfs file systems.
 +
 
 +
=== Converting a file system from Ext3/4 ===
 +
 
 +
{{Warning| As of mid-to-late 2015, there are many reports on the btrfs mailing list about incomplete/corrupt/broken conversions. The situation is improving as patches are being submitted, but proceed very carefully. Make sure you have ''working'' backups of any data you cannot afford to lose. See [https://btrfs.wiki.kernel.org/index.php/Conversion_from_Ext3 Conversion from Ext3] on the btrfs wiki.}}
  
 
Boot from an install CD, then convert by doing:
 
Boot from an install CD, then convert by doing:
Line 46: Line 84:
 
  # btrfs-convert /dev/''partition''
 
  # btrfs-convert /dev/''partition''
  
Mount the partion and test the conversion by checking the files.  Be sure to change the {{ic|/etc/fstab}} to reflect the change ('''type''' to btrfs and '''fs_passno''' [the last field] to 0 as Btrfs does not do a file system check on boot). Also note that the UUID of the partition will have changed, so update your fstab accordingly if you use UUIDs. {{ic|chroot}} into the system and rebuild the GRUB menu list (see [[Install from Existing Linux]] and [[GRUB]] articles).
+
Mount the partion and test the conversion by checking the files.  Be sure to change the {{ic|/etc/fstab}} to reflect the change ('''type''' to {{ic|btrfs}} and '''fs_passno''' [the last field] to {{ic|0}} as Btrfs does not do a file system check on boot). Also note that the UUID of the partition will have changed, so update fstab accordingly when using UUIDs. {{ic|chroot}} into the system and rebuild the GRUB menu list (see [[Install from existing Linux]] and [[GRUB]] articles). If converting a root filesystem, while still chrooted run {{ic|mkinitcpio -p linux}} to regenerate the initramfs or the system will not successfully boot. If you get stuck in grub with 'unknown filesystem' try reinstalling grub with {{ic|grub-install /dev/''partition''}} and regenerate the config as well {{ic|grub-mkconfig -o /boot/grub/grub.cfg}}.
  
To complete, delete the saved image, delete the sub-volume that image is on, then balance the drive to reclaim the space.
+
After confirming that there are no problems, complete the conversion by deleting the backup {{ic|ext2_saved}} sub-volume. Note that you cannot revert back to ext3/4 without it.
  
# rm /ext2_saved/*
 
 
  # btrfs subvolume delete /ext2_saved
 
  # btrfs subvolume delete /ext2_saved
  
=== Displaying used/free space ===
+
Finally [[#Balance|balance]] the file system to reclaim the space.
  
General linux userspace tools such as {{ic|/usr/bin/df}} will inaccurately report free space on a Btrfs partition since it does not take into account space allocated for and used by the metadata. It is recommended to use {{ic|/usr/bin/btrfs}} to query a btrfs partition. Below is an illustration of this effect, first querying using df, and then using btrfs fi df:
+
== Configuring the file system ==
  
{{hc|# df -h /|
+
=== Copy-On-Write (CoW) ===
Filesystem      Size  Used Avail Use% Mounted on
+
/dev/sda3      119G  3.0G  116G  3% /
+
}}
+
  
{{hc|# btrfs fi df /|2=
+
By default, Btrfs uses [[Wikipedia:copy-on-write]] for all files all the time. See [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Copy_on_Write_.28CoW.29 the Btrfs Sysadmin Guide section]] for implementation details, as well as advantages and disadvantages.
Data: total=3.01GB, used=2.73GB
+
System: total=4.00MB, used=16.00KB
+
Metadata: total=1.01GB, used=181.83MB
+
}}
+
  
Notice that {{ic|df -h}} reports 3.0GB used but {{ic|btrfs fi df}} reports 2.73GB for the data. This is due to the way BTRFS allocates space into the pool. The true disk usage is the sum of all three 'used' values which is inferior to 3.0GB as reported by {{ic|df -h}}.
+
==== Disabling CoW ====
  
Another useful command to show a less verbose readout of used space is {{ic|btrfs fi show}}:
+
To disable copy-on-write for newly created files in a mounted subvolume, use the {{ic|nodatacow}} mount option. This will only affect newly created files. Copy-on-write will still happen for existing files.
  
{{hc|# btrfs fi show /dev/sda3|
+
To disable copy-on-write for single files/directories do:
failed to open /dev/sr0: No medium found
+
Label: 'arch64'  uuid: 02ad2ea2-be12-2233-8765-9e0a48e9303a
+
Total devices 1 FS bytes used 2.91GB
+
devid    1 size 118.95GB used 4.02GB path /dev/sda2
+
  
Btrfs v0.20-rc1-358-g194aa4a-dirty
+
$ chattr +C ''/dir/file''
 +
 
 +
This will disable copy-on-write for those operation in which there is only one reference to the file. If there is more than one reference (e.g. through {{ic|1=cp --reflink=always}} or because of a filesystem snapshot), copy-on-write still occurs.
 +
 
 +
{{Note|From chattr man page: "For btrfs, the 'C' flag should be set on new or empty files. If it is set on a file which already has data blocks, it is undefined when the blocks assigned to the file will be fully stable. If the 'C' flag is set on a directory, it will have no effect on the directory, but new files created in that directory will have the No_COW attribute."}}
 +
 
 +
{{Tip|In accordance with the note above, you can use the following trick to disable copy-on-write on existing files in a directory:
 +
$ mv ''/path/to/dir'' ''/path/to/dir''_old
 +
$ mkdir ''/path/to/dir''
 +
$ chattr +C ''/path/to/dir''
 +
$ cp -a ''/path/to/dir''_old/* ''/path/to/dir''
 +
$ rm -rf ''/path/to/dir''_old
 +
Make sure that the data are not used during this process. Also note that {{ic|mv}} or {{ic|cp --reflink}} as described below will not work.
 
}}
 
}}
  
== Limitations ==
+
==== Forcing CoW ====
  
A few limitations should be known before trying.
+
To force copy-on-write when copying files use:
  
=== Encryption ===
+
$ cp --reflink ''source'' ''dest''
  
Btrfs has no built-in encryption support (this may come in future), but you can encrypt the partition before running {{ic|mkfs.btrfs}}. See [[Dm-crypt with LUKS]].  
+
This would only be required if CoW was disabled for the file to be copied (as implemented above). See the man page on {{ic|cp}} for more details on the {{ic|--reflink}} flag.
  
If you've already created a Btrfs file system, you can also use something like [[EncFS]] or [[TrueCrypt]], though perhaps without some of Btrfs' features.
+
=== Compression ===
  
=== Swap file ===
+
Btrfs supports transparent compression, meaning every file on the partition is automatically compressed. This not only reduces the size of files, but also [http://www.phoronix.com/scan.php?page=article&item=btrfs_compress_2635&num=1 improves performance], in particular if using the [http://www.phoronix.com/scan.php?page=article&item=btrfs_lzo_2638&num=1 lzo algorithm], in some specific use cases (e.g. single thread with heavy file IO), while obviously harming performance on other cases (e.g. multithreaded and/or cpu intensive tasks with large file IO).
  
Btrfs does not support swap files. This is due to swap files requiring a function that Btrfs doesn't have for possibility of corruptions.<sup>[https://btrfs.wiki.kernel.org/index.php/FAQ#Does_btrfs_support_swap_files.3F link]</sup> A swap file can be mounted on a loop device with poorer performance but will not be able to hibernate. A ''systemd'' service file is available {{AUR|systemd-loop-swapfile}}.
+
Compression is enabled using the {{ic|1=compress=zlib}} or {{ic|1=compress=lzo}} mount options. Only files created or modified after the mount option is added will be compressed. However, it can be applied quite easily to existing files (e.g. after a conversion from ext3/4) using the {{ic|btrfs filesystem defragment -c''alg''}} command, where {{ic|''alg''}} is either {{ic|zlib}} or {{ic|lzo}}. In order to re-compress the whole file system with {{pkg|lzo}}, run the following command:
  
=== GRUB2 and core.img ===
+
# btrfs filesystem defragment -r -v -clzo /
  
[[GRUB]] can boot Btrfs partitions however the module is larger than e.g. ext4 and the {{ic|core.img}} file made by ''grub-install'' may not fit between the MBR and the first partition. This can be solved by using GPT or by putting an extra 1 or 2 MB of free space before the first partition.
+
{{Tip|Compression can also be enabled per-file without using the {{ic|compress}} mount option; simply apply {{ic|chattr +c}} to the file. When applied to directories, it will cause new files to be automatically compressed as they come.}}
  
If you get the following: {{ic|1=error no such device: root}} when booting from a RAID style setup then edit /usr/share/grub/grub-mkconfig_lib and remove both quotes from the line {{ic|1=echo "  search --no-floppy --fs-uuid --set=root ${hints} ${fs_uuid}"}}. Regenerate the config for grub and your system should boot without an error.
+
When installing Arch to an empty Btrfs partition, use the {{ic|compress}} option when [[Beginners' guide#Format the file systems and enable swap|mounting the filesystem]]: {{ic|1=mount -o compress=lzo /dev/sd''xY'' /mnt/}}. During [[Beginners' guide#Configuration|configuration]], add {{ic|1=compress=lzo}} to the mount options of the root file system in [[fstab]].
  
== Features ==
+
=== Subvolumes ===
  
Various features are available and can be adjusted.
+
"A btrfs subvolume is not a block device (and cannot be treated as one) instead, a btrfs subvolume can be thought of as a POSIX file namespace. This namespace can be accessed via the top-level subvolume of the filesystem, or it can be mounted in its own right." [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Subvolumes]
  
=== Copy-On-Write (CoW) ===
+
Each Btrfs file system has a top-level subvolume with ID 5. It can be mounted as {{ic|/}} (by default), or another subvolume can be [[#Mounting subvolumes|mounted]] instead.
 +
 
 +
See the following links for more details:
 +
* [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Subvolumes Btrfs Wiki SysadminGuide#Subvolumes]
 +
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Basic_Filesystem_Commands Btrfs Wiki Getting started#Basic Filesystem Commands]
 +
* [https://btrfs.wiki.kernel.org/index.php/Trees Btrfs Wiki Trees]
 +
 
 +
==== Creating a subvolume ====
 +
 
 +
To create a subvolume:
 +
 
 +
# btrfs subvolume create ''/path/to/subvolume''
 +
 
 +
==== Listing subvolumes ====
 +
 
 +
To see a list of current subvolumes under {{ic|''path''}}:
 +
 
 +
# btrfs subvolume list -p ''path''
 +
 
 +
==== Deleting a subvolume ====
 +
 
 +
To delete a subvolume:
 +
 
 +
# btrfs subvolume delete ''/path/to/subvolume''
 +
 
 +
Attempting to remove the directory {{ic|''/path/to/subvolume''}} without using the above command will not delete the subvolume.
 +
 
 +
==== Mounting subvolumes ====
 +
 
 +
Subvolumes can be mounted like file system partitions using the {{ic|1=subvol=''/path/to/subvolume''}} or {{ic|1=subvolid=''objectid''}} mount flags. For example, you could have a subvolume named {{ic|subvol_root}} and mount it as {{ic|/}}.  One can mimic traditional file system partitions by creating various subvolumes under the top level of the file system and then mounting them at the appropriate mount points. Thus one can easily restore a file system (or part of it) to a previous state easily using [[#Snapshots]].
 +
 
 +
{{Tip|1= Changing subvolume layouts is made simpler by not using the toplevel subvolume (ID=5) as {{ic|/}} (which is done by default). Instead, consider creating a subvolume to house your actual data and mounting it as {{ic|/}}.}}
 +
 
 +
See [[Snapper#Suggested filesystem layout]], [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Managing_Snapshots Btrfs SysadminGuide#Managing Snapshots], and [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Layout Btrfs SysadminGuide#Layout] for example file system layouts using subvolumes.
 +
 
 +
===== Mount options =====
 +
 
 +
When mounting subvolumes with {{ic|1=subvol=}} several mount options are available. For example, mount options that affect [[#Compression]] or [[#Copy-On-Write (CoW)]] can be used.
 +
 
 +
See [https://btrfs.wiki.kernel.org/index.php/Mount_options Btrfs Wiki Mount options] and [https://btrfs.wiki.kernel.org/index.php/Gotchas Btrfs Wiki Gotchas] for more information. In addition to configurations that can be made during or after file system creation, the various mount options for Btrfs can drastically change its performance characteristics. As this is a file system that is still in active development, changes and regressions should be expected. See links in the [[#See also]] section for some benchmarks.
 +
 
 +
{{Warning|Specific mount options can disable safety features and increase the risk of complete file system corruption.}}
 +
 
 +
==== Changing the default sub-volume ====
 +
 
 +
The default sub-volume is mounted if no {{ic|1=subvol=}} mount option is provided. To change the default subvolume, do:
 +
 
 +
# btrfs subvolume set-default ''subvolume-id'' /
 +
 
 +
where ''subvolume-id'' can be found by [[#Listing subvolumes|listing]].
 +
 
 +
{{Note|1=After changing the default subvolume on a system with [[GRUB]], you should run {{ic|grub-install}} again to notify the bootloader of the changes. See [https://bbs.archlinux.org/viewtopic.php?pid=1615373 this forum thread].}}
 +
 
 +
{{Warning|Changing the default subvolume with {{ic|btrfs subvolume set-default}} will make the top level of the filesystem inaccessible when the default subvolume is mounted . Reference: [https://btrfs.wiki.kernel.org/index.php/SysadminGuide Btrfs Wiki Sysadmin Guide].}}
 +
 
 +
=== Commit interval settings ===
  
The resolution at which data are written to the filesystem is dictated by Btrfs itself and by system-wide settings. Btrfs defaults to a 30 seconds checkpoint interval in which new data are committed to the filesystem. As of Btrfs v0.20-rc1-253-g7854c8b users cannot tweak this without recompiling a [http://www.mail-archive.com/linux-btrfs@vger.kernel.org/msg26090.html patched version of fs/btrfs/disk-io.c]. On 01-Aug-2013, David Sterba submitted [http://www.mail-archive.com/linux-btrfs@vger.kernel.org/msg26116.html this patch] to make this a formal mount time tuneable.
+
The resolution at which data are written to the filesystem is dictated by Btrfs itself and by system-wide settings. Btrfs defaults to a 30 seconds checkpoint interval in which new data are committed to the filesystem. This is tuneable using mount options (see below)
  
 
System-wide settings also affect commit intervals. They include the files under {{ic|/proc/sys/vm/*}} and are out-of-scope of this wiki article. The kernel documentation for them resides in {{ic|Documentation/sysctl/vm.txt}}.
 
System-wide settings also affect commit intervals. They include the files under {{ic|/proc/sys/vm/*}} and are out-of-scope of this wiki article. The kernel documentation for them resides in {{ic|Documentation/sysctl/vm.txt}}.
  
CoW comes with some advantages, but can negatively affect performance with large files that have small random writes. It is recommended to disable CoW for database files and virtual machine images.
+
=== Checkpoint interval ===
You can disable CoW for the entire block device by mounting it with {{ic|nodatacow}} option. However, this will disable CoW for the entire file system.
+
  
To disable CoW for single files/directories do:
+
Starting with Linux 3.12, users are able to change the checkpoint interval from the default 30 s to any value by appending the {{ic|commit}} mount option in {{ic|/etc/fstab}} for the btrfs partition.
  
  # chattr +C ''/dir/file''
+
  LABEL=arch64 / btrfs defaults,noatime,ssd,compress=lzo,commit=120 0 0
  
Note, from chattr man page: For btrfs, the 'C' flag should be set on new or empty files.  If it is set on a file which already has data blocks, it is undefined when the blocks assigned to the file will be fully stable. If the 'C' flag is set on a directory, it will have no effect on the directory, but new files created in that directory will have the No_COW attribute.
+
=== SSD TRIM ===
 +
A Btrfs filesystem will automatically free unused blocks from an SSD drive supporting the TRIM command.
  
Likewise, to save space by forcing CoW when copying files use:
+
More information about enabling and using TRIM can be found in [[Solid State Drives#TRIM]].
  
# cp --reflink source dest
+
== Usage ==
  
As dest file is changed, only those blocks that are changed from source will be written to the disk. One might consider aliasing aliasing ''cp'' to {{ic|1=cp --reflink=auto}}.
+
=== Displaying used/free space ===
  
=== Multi-device filesystem and RAID feature ===
+
General linux userspace tools such as {{ic|/usr/bin/df}} will inaccurately report free space on a Btrfs partition since it does not take into account space allocated for and used by the metadata. It is recommended to use {{ic|/usr/bin/btrfs}} to query a Btrfs partition. Below is an illustration of this effect, first querying using {{ic|df -h}}, and then using {{ic|btrfs filesystem df}}:
  
==== Multi-device filesystem ====
+
{{hc|$ df -h /|
 +
Filesystem      Size  Used Avail Use% Mounted on
 +
/dev/sda3      119G  3.0G  116G  3% /
 +
}}
  
When creating a ''btrfs'' filesystem, you can pass as many partitions or disk devices as you want to ''mkfs.btrfs''. The filesystem will be created across these devices. You can '''"'''pool'''"''' this way, multiple partitions or devices to get a big ''btrfs'' filesystem.
+
{{hc|$ btrfs filesystem df /|2=
 +
Data: total=3.01GB, used=2.73GB
 +
System: total=4.00MB, used=16.00KB
 +
Metadata: total=1.01GB, used=181.83MB
 +
}}
  
You can also add or remove device from an existing btrfs filesystem (caution is mandatory).
+
Notice that {{ic|df -h}} reports 3.0GB used but {{ic|btrfs filesystem df}} reports 2.73GB for the data. This is due to the way Btrfs allocates space into the pool. The true disk usage is the sum of all three 'used' values which is inferior to 3.0GB as reported by {{ic|df -h}}.
  
A multi-device ''btrfs'' filesystem (also called a btrfs volume) is not recognized until
+
{{Note|1=If you see an entry of type {{ic|unknown}} in the output of {{ic|btrfs filesystem df}} at kernel >= 3.15, this is a display bug. As of [http://thread.gmane.org/gmane.comp.file-systems.btrfs/34419 this patch], the entry means GlobalReserve, which is kind of a buffer for changes not yet flushed. This entry is displayed as {{ic|unknown, single}} in RAID setups and is not possible to re-balance.}}
# btrfs device scan
+
has been run. This is the purpose of the ''btrfs'' mkinitcpio hook.
+
  
==== RAID features ====
+
Another useful command to show a less verbose readout of used space is {{ic|btrfs filesystem show}}:
  
When creating multi-device filesystem, you can also specify to use RAID0, RAID1 or RAID10 across the devices you have added to the filesystem. RAID levels can be applied independently to data and meta data. By default, meta data is duplicated on single volumes or RAID1 on multi-disk sets.
+
# btrfs filesystem show /dev/sda3
  
btrfs works in block-pairs for raid0, raid1, and raid10. This means:
+
The newest command to get information on free/used space of a is {{ic|btrfs filesystem usage}}:
  
raid0 - block-pair stripped across 2 devices
+
# btrfs filesystem usage
  
raid1 - block-pair written to 2 devices
+
{{Note|1=The {{ic|btrfs filesystem usage}} command does not currently work correctly with {{ic|RAID5/RAID6}} RAID levels.}}
  
For 2 disk sets, this matches raid levels as defined in md-raid (mdadm). For 3+ disk-sets, the result is entirely different than md-raid.  
+
=== Defragmentation ===
 +
 
 +
Btrfs supports online defragmentation. To defragment the metadata of the root folder:
 +
 
 +
# btrfs filesystem defragment /
 +
 
 +
This ''will not'' defragment the entire file system. For more information read [https://btrfs.wiki.kernel.org/index.php/Problem_FAQ#Defragmenting_a_directory_doesn.27t_work this page] on the Btrfs wiki.
 +
 
 +
To defragment the entire file system verbosely:
  
For example:
+
# btrfs filesystem defragment -r -v /
  
3 1TB disks in an md based raid1 yields a {{ic|/dev/md0}} with 1 TB free space and the ability to safely loose 2 disks without losing data.
+
=== Scrub ===
3 1TB disks in a Btrfs volume with data=raid1 will allow the storage of approximately 1.5 TB of data before reporting full. Only 1 disk can safely be lost without losing data.
+
The [https://btrfs.wiki.kernel.org/index.php/Glossary Btrfs Wiki Glossary] says that Btrfs scrub is "[a]n online filesystem checking tool. Reads all the data and metadata on the filesystem, and uses checksums and the duplicate copies from RAID storage to identify and repair any corrupt data."
  
Btrfs uses a round-robin scheme to decide how block-pairs are spread among disks. As of Linux 3.0, a quasi-round-robin scheme is used which prefers larger disks when distributing block pairs. This allows raid0 and raid1 to take advantage of most (and sometimes all) space in a disk set made of multiple disks. For example, a set consisting of a 1TB disk and 2 500GB disks with data=raid1 will place a copy of every block on the 1TB disk and alternate (round-robin) placing blocks on each of the 500GB disks. Full space utilization will be made. A set made from a 1TB disk, a 750GB disk, and a 500GB disk will work the same, but the filesystem will report full with 250GB unusable on the 750GB disk. To always take advantage of the full space (even in the last example), use data=single. (data=single is akin to JBOD defined by some raid controllers) See [https://btrfs.wiki.kernel.org/index.php/FAQ#How_much_space_do_I_get_with_unequal_devices_in_RAID-1_mode.3F the BTRFS FAQ] for more info.
+
# btrfs scrub start /
 +
# btrfs scrub status /
  
=== Sub-volumes ===
+
{{Warning|The running scrub process will prevent the system from suspending, see [http://comments.gmane.org/gmane.comp.file-systems.btrfs/33106 this thread] for details.}}
  
One of the features of Btrfs is the use of sub-volumes. Sub-volumes are basically a named btree that holds files and directories. They have inodes inside the tree of tree roots and can have non-root owners and groups. Sub-volumes can optionally be given a quota of blocks. All of the blocks and file extents inside of sub-volumes are reference counted to allow snapshotting. This is similar to the dynamically expanding storage of a virtual machine that will only use as much space on a device as needed, eliminating several half-filled partitions.  One can also mount the sub-volumes with different mount options, giving more flexibility in security.  
+
The {{Pkg|btrfs-progs}} package brings the {{ic|btrfs-scrub@.timer}} unit for monthly scrubbing the specified mountpoint. [[Enable]] the timer with an encoded path, e.g. {{ic|btrfs-scrub@-.timer}} for {{ic|/}} and {{ic|btrfs-scrub@home.timer}} for {{ic|/home}}.
  
To create a sub-volume:
+
You can also run the scrub manually by [[starting]] {{ic|btrfs-scrub@.service}} (with the same encoded path). The advantage of this over {{ic|# btrfs scrub}} is that the results of the scrub will be logged in the [[systemd journal]].
  
# btrfs subvolume create [''dest''/]
+
=== Balance ===
  
For increased flexibility, install your system into a dedicated sub-volume, and, in the kernel boot parameters, use:
+
"A balance passes all data in the filesystem through the allocator again. It is primarily intended to rebalance the data in the filesystem across the devices when a device is added or removed. A balance will regenerate missing copies for the redundant RAID levels, if a device has failed." [https://btrfs.wiki.kernel.org/index.php/Glossary] See [https://btrfs.wiki.kernel.org/index.php/FAQ#What_does_.22balance.22_do.3F Upstream FAQ page].
  
  rootflags=subvol=''whatever you called the subvol''
+
  # btrfs balance start /
 +
# btrfs balance status /
  
This makes system rollbacks possible.
+
=== RAID ===
  
If using for the root partition, it is advisable to add '''crc32c''' (or '''crc32c-intel''' for Intel machines) to the modules array in {{ic|/etc/mkinitcpio.conf}}.
+
Btrfs offers native "RAID" for [[#Multi-device file system]]s. Notable features which set btrfs RAID apart from [[mdadm]] are self-healing redundant arrays and online balancing. See [https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices the Btrfs wiki page] for more information. The Btrfs sysadmin page also [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#RAID_and_data_replication has a section] with some more technical background.
  
 
=== Snapshots ===
 
=== Snapshots ===
 +
 +
"A snapshot is simply a subvolume that shares its data (and metadata) with some other subvolume, using btrfs's COW capabilities." See [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Snapshots Btrfs Wiki SysadminGuide#Snapshots] for details.
  
 
To create a snapshot:
 
To create a snapshot:
Line 179: Line 289:
 
  # btrfs subvolume snapshot ''source'' [''dest''/]''name''
 
  # btrfs subvolume snapshot ''source'' [''dest''/]''name''
  
Snapshots are not recursive, this means that every subvolume inside subvolume will be an empty directory inside the snapshot.
+
To create a readonly snapshot add the {{ic|-r}} flag. To create writable version of a readonly snapshot, simply create a snapshot of it.
  
=== Defragmentation ===
+
{{Note|Snapshots are not recursive. Every sub-volume inside sub-volume will be an empty directory inside the snapshot.}}
  
Btrfs supports online defragmentation. To defragment the metadata of the root folder do:
+
=== Send/receive ===
  
# btrfs filesystem defragment /
+
A subvolume can be sent to stdout or a file using the {{ic|send}} command. This is usually most useful when piped to a Btrfs {{ic|receive}} command. For example, to send a snapshot named {{ic|/root_backup}} (perhaps of a snapshot you made of {{ic|/}} earlier) to {{ic|/backup}} you would do the following:
  
This ''will not'' defragment the entire system. For more information read [https://btrfs.wiki.kernel.org/index.php/Problem_FAQ#Defragmenting_a_directory_doesn.27t_work this page] on the btrfs wiki.
+
  # btrfs send /root_backup | btrfs receive /backup
  
To defragment the entire system verbosely do:
+
The snapshot that is sent ''must'' be readonly. The above command is useful for copying a subvolume to an external device (''e.g.'', a USB disk mounted at {{ic|/backup}} above).
  
# find / -xdev -type f -print -exec btrfs filesystem defrag '{}' \;
+
You can also send only the difference between two snapshots. For example, if you have already sent a copy of {{ic|root_backup}} above and have made a new readonly snapshot on your system named {{ic|root_backup_new}}, then to send only the incremental difference to {{ic|/backup}} do:
  
=== Compression ===
+
  # btrfs send -p /root_backup /root_backup_new | btrfs send /backup
  
Btrfs supports transparent compression, which means every file on the partition is automatically compressed. This does not only reduce the size of those files, but also [http://www.phoronix.com/scan.php?page=article&item=btrfs_compress_2635&num=1 improves performance], in particular if using the [http://www.phoronix.com/scan.php?page=article&item=btrfs_lzo_2638&num=1 lzo algorithm], in some specific use cases (e.g. single tread with heavy file IO), while obviously harming performance on other cases (e.g. multithreaded and/or cpu intensive tasks with large file IO). Compression is enabled using the {{ic|1=compress=gzip}} or {{ic|1=compress=lzo}} mount options. Only files created or modified after the mount option is added will be compressed, so to fully benefit from compression it should be enabled during installation.  
+
Now a new subvolume named {{ic|root_backup_new}} will be present in {{ic|/backup}}.
  
However, it can quite easily be applied to a subvolume using the defragment -czlib (or whichever algorithm you so choose) command (the same command above could be used, by adding the -czlib and such, to recursively apply). Also keep in mind that for future files to be compressed, a simple {{ic|chattr +c}} should be applied to some directories, so as to automatically compress new files as they come.
+
See [https://btrfs.wiki.kernel.org/index.php/Incremental_Backup Btrfs Wiki's Incremental Backup page] on how to use this for an incremental backup and for tools that automate the process.
  
After [[Beginners%27_Guide#Prepare_the_storage_drive|preparing the storage drive]], simply switch to another terminal ({{ic|Ctrl+Alt+number}}), and run the following command:
+
== Limitations ==
  
# mount -o remount,compress=lzo /dev/sd''XY'' /mnt/target
+
A few limitations should be known before trying.
  
After the installation is finished, add {{ic|1=compress=lzo}} to the mount options of the root filesystem in {{ic|/etc/[[fstab]]}}.
+
=== Encryption ===
  
=== Checkpoint Interval ===
+
Btrfs has no built-in encryption support, but this may come in future. Users can encrypt the partition before running {{ic|mkfs.btrfs}}. See [[dm-crypt/Encrypting an entire system#Btrfs subvolumes with swap]].
  
Starting with Linux 3.12, users are able to change the checkpoint interval from the default 30 s to any value by appending the '''commit''' mount flag in {{ic|/etc/fstab}} for the btrfs partition.
+
Existing Btrfs file systems can use something like [[EncFS]] or [[TrueCrypt]], though perhaps without some of Btrfs' features.
  
LABEL=arch64 / btrfs defaults,noatime,ssd,compress=lzo,commit=120 0 0
+
=== Swap file ===
  
=== Partitioning ===
+
Btrfs does not yet support [[Swap#Swap_file|swap files]]. This is due to swap files requiring a function that Btrfs does not have for possibility of file system corruption [https://btrfs.wiki.kernel.org/index.php/FAQ#Does_btrfs_support_swap_files.3F]. Patches for swapfile support are already available [https://lkml.org/lkml/2014/12/9/718] and may be included in an upcoming kernel release. As an alternative a swap file can be mounted on a loop device with poorer performance but will not be able to hibernate. Install the package {{Pkg|systemd-swap}} from the [[official repositories]] to automate this.
  
Btrfs can occupy an entire data storage device and replace the [[MBR]] or [[GPT]] partitioning schemes. You can use [[Btrfs#Sub-volumes|subvolumes]] to simulate partitions. There are some limitations to this approach if you use only a single disk:
+
=== Linux-rt kernel ===
  
* You can not use different [[File_Systems|file systems]] for different [[fstab|mount points]].
+
As of version 3.14.12_rt9, the [[Kernel#-rt|linux-rt]] kernel does not boot with the Btrfs file system. This is due to the slow development of the ''rt'' patchset.
* You can not use [[Swap|swap area]] as Btrfs does not support [[Swap#Swap_file|swap files]] and there is no place to create [[Swap#Swap_partition|swap partition]].
+
* You can not use [[UEFI]] to boot.
+
  
To overwrite the existing partition table with Btrfs, run the following command:
+
== Tips and tricks ==
# mkfs.btrfs /dev/sd''X''
+
Do not specify {{ic|/dev/sda''X''}} or it will format an existing partition instead of replacing the entire partitioning scheme.
+
  
Install your [[Bootloaders|boot loader]] the same way you install it for a data storage device with a [[MBR|Master Boot Record]]. For example:
+
See [[Btrfs - Tips and tricks]].
# grub-install --recheck /dev/sd''X''
+
 
for [[Grub#Install_to_440-byte_MBR_boot_code_region|GRUB]].
+
== Troubleshooting ==
 +
 
 +
See the [https://btrfs.wiki.kernel.org/index.php/Problem_FAQ Btrfs Problem FAQ] for general troubleshooting.
 +
 
 +
=== GRUB ===
 +
 
 +
==== Partition offset ====
 +
 
 +
{{Note|1=The offset problem may happen when you try to embed {{ic|core.img}} into a partitioned disk. It means that [https://wiki.archlinux.org/index.php?title=Talk:Btrfs&diff=319474&oldid=292530 it is OK] to embed grub's {{ic|corg.img}} into a Btrfs pool on a partitionless disk (e.g. {{ic|/dev/sd''X''}}) directly.}}
 +
 
 +
[[GRUB]] can boot Btrfs partitions however the module may be larger than other [[file systems]]. And the {{ic|core.img}} file made by {{ic|grub-install}} may not fit in the first 63 sectors (31.5KiB) of the drive between the MBR and the first partition. Up-to-date partitioning tools such as {{ic|fdisk}} and {{ic|gdisk}} avoid this issue by offsetting the first partition by roughly 1MiB or 2MiB.
 +
 
 +
==== Missing root ====
 +
 
 +
Users experiencing the following: {{ic|1=error no such device: root}} when booting from a RAID style setup then edit /usr/share/grub/grub-mkconfig_lib and remove both quotes from the line {{ic|1=echo "  search --no-floppy --fs-uuid --set=root ${hints} ${fs_uuid}"}}. Regenerate the config for grub and the system should boot without an error.
 +
 
 +
=== BTRFS: open_ctree failed ===
 +
 
 +
As of November 2014 there seems to be a bug in [[systemd]] or [[mkinitcpio]] causing the following error on systems with multi-device Btrfs filesystem using the {{ic|btrfs}} hook in {{ic|mkinitcpio.conf}}:
 +
 
 +
{{bc|<nowiki>
 +
BTRFS: open_ctree failed
 +
mount: wrong fs type, bad option, bad superblock on /dev/sdb2, missing codepage or helper program, or other error
 +
 
 +
In some cases useful info is found in syslog - try dmesg|tail or so.
 +
 
 +
You are now being dropped into an emergency shell.
 +
</nowiki>}}
 +
 
 +
A workaround is to remove {{ic|btrfs}} from the {{ic|HOOKS}} array in {{ic|/etc/mkinitcpio.conf}} and instead add {{ic|btrfs}} to the {{ic|MODULES}} array. Then regenerate the initramfs with {{ic|mkinitcpio -p linux}} (adjust the preset if needed) and reboot.
 +
 
 +
See the [https://bbs.archlinux.org/viewtopic.php?id=189845 original forums thread] and {{Bug|42884}} for further information and discussion.
 +
 
 +
You will get the same error if you try to mount a raid array without one of the devices. In that case you must add the {{ic|degraded}} mount option to {{ic|/etc/fstab}}. If your root resides on the array, you must also add {{ic|1=rootflags=degraded}} to your [[kernel parameters]].
 +
 
 +
=== btrfs check ===
 +
{{Warning|Since Btrfs is under heavy development, especially the {{ic|btrfs check}} command, it is highly recommended to create a '''backup''' and consult the following Btfrs documentation before executing {{ic|btrfs check}} with the {{ic|--repair}} switch.}}
 +
 
 +
The ''[https://btrfs.wiki.kernel.org/index.php/Manpage/btrfs-check btrfs check]'' command can be used to check or repair an unmounted Btrfs filesystem. However, this repair tool is still immature and not able to repair certain filesystem errors even those that do not render the filesystem unmountable.
 +
 
 +
See [https://btrfs.wiki.kernel.org/index.php/Btrfsck Btrfsck] for more information.
  
 
== See also ==
 
== See also ==
  
* [https://btrfs.wiki.kernel.org/ Btrfs Wiki]
+
* '''Official site'''
* [https://btrfs.wiki.kernel.org/index.php/Problem_FAQ BTRFS Problem FAQ] - Official FAQ
+
** [https://btrfs.wiki.kernel.org/ Btrfs Wiki]
* [http://www.funtoo.org/wiki/BTRFS_Fun Funtoo Btrfs wiki entry] - Very well-written article
+
** [https://btrfs.wiki.kernel.org/index.php/Glossary Btrfs Wiki Glossary]
* [http://www.phoronix.com/scan.php?page=news_item&px=MTA0ODU Avi Miller presenting BTRFS] at SCALE 10x.  Jan/2012.
+
* '''Official FAQs'''
* [http://www.phoronix.com/scan.php?page=news_item&px=MTA4Mzc Summary of Chris Mason's talk from LFCS 2012]
+
** [https://btrfs.wiki.kernel.org/index.php/FAQ Btrfs Wiki FAQ]
 +
** [https://btrfs.wiki.kernel.org/index.php/Problem_FAQ Btrfs Wiki Problem FAQ]
 +
* '''Btrfs pull requests'''
 +
** [http://lkml.indiana.edu/hypermail/linux/kernel/1401.3/03045.html 3.14]
 +
** [http://lkml.indiana.edu/hypermail/linux/kernel/1311.1/03526.html 3.13]
 +
** [http://lkml.indiana.edu/hypermail/linux/kernel/1309.1/02981.html 3.12]
 +
** [http://lkml.indiana.edu/hypermail/linux/kernel/1305.1/01064.html 3.11]
 +
* '''Performance related'''
 +
** [http://superuser.com/questions/432188/should-i-put-my-multi-device-btrfs-filesystem-on-disk-partitions-or-raw-devices Btrfs on raw disks?]
 +
** [http://comments.gmane.org/gmane.comp.file-systems.btrfs/19440 Varying leafsize and nodesize in Btrfs]
 +
** [http://comments.gmane.org/gmane.comp.file-systems.btrfs/15646 Btrfs support for efficient SSD operation (data blocks alignment)]
 +
** [https://btrfs.wiki.kernel.org/index.php/FAQ#Is_Btrfs_optimized_for_SSD.3F Is Btrfs optimized for SSDs?]
 +
** '''Phoronix mount option benchmarking'''
 +
*** [http://www.phoronix.com/scan.php?page=article&item=linux_314_btrfs Linux 3.14]
 +
*** [http://www.phoronix.com/scan.php?page=article&item=linux_btrfs_311&num=1 Linux 3.11]
 +
*** [http://www.phoronix.com/scan.php?page=news_item&px=MTM0OTU Linux 3.9]
 +
*** [http://www.phoronix.com/scan.php?page=article&item=btrfs_linux37_mounts&num=1 Linux 3.7]
 +
*** [http://www.phoronix.com/scan.php?page=article&item=linux_btrfs_options&num=1 Linux 3.2]
 +
** [http://blog.erdemagaoglu.com/post/4605524309/lzo-vs-snappy-vs-lzf-vs-zlib-a-comparison-of Lzo vs. zLib]
 +
* '''Miscellaneous'''
 +
** [http://www.funtoo.org/wiki/BTRFS_Fun Funtoo Wiki Btrfs Fun]
 +
** [http://www.phoronix.com/scan.php?page=news_item&px=MTA0ODU Avi Miller presenting Btrfs] at SCALE 10x, January 2012.
 +
** [http://www.phoronix.com/scan.php?page=news_item&px=MTA4Mzc Summary of Chris Mason's talk] from LFCS 2012
 +
** [http://git.kernel.org/?p&#61;linux/kernel/git/torvalds/linux-2.6.git;a&#61;commit;h&#61;35054394c4b3cecd52577c2662c84da1f3e73525 Btrfs: stop providing a bmap operation to avoid swapfile corruptions] 2009-01-21
 +
** [http://marc.merlins.org/perso/btrfs/post_2014-03-22_Btrfs-Tips_-Doing-Fast-Incremental-Backups-With-Btrfs-Send-and-Receive.html Doing Fast Incremental Backups With Btrfs Send and Receive]

Latest revision as of 01:40, 28 April 2016

From Wikipedia:Btrfs:

Btrfs (B-tree file system, pronounced as "butter F S", "better F S", "b-tree F S", or simply by spelling it out) is a file system based on the copy-on-write (COW) principle, initially designed at Oracle Corporation for use in Linux. The development of Btrfs began in 2007, and by August 2014, the file system's on-disk format has been marked as stable.

From Btrfs Wiki:

Btrfs is a new copy on write (CoW) filesystem for Linux aimed at implementing advanced features while focusing on fault tolerance, repair and easy administration. Jointly developed at Oracle, Red Hat, Fujitsu, Intel, SUSE, STRATO and many others, Btrfs is licensed under the GPL and open for contribution from anyone.
Warning:

Preparation

The official kernels linux and linux-lts include support for Btrfs. Additionally GRUB, mkinitcpio, and Syslinux have support for Btrfs and require no additional configuration.

User space utilities are available by installing the btrfs-progs package.

Partitioning

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: Grub#Install_to_partition_or_partitionless_disk warns against using it on a partitionless disk. (Discuss in Talk:Btrfs#)

Btrfs can occupy an entire data storage device, replacing the MBR or GPT partitioning schemes; however, this is not required to simply create a Btrfs filesystem on an existing partition that was created using another method. If using Btrfs for partitioning, one can use subvolumes to simulate partitions. There are some limitations to this approach in single disk setups:

To overwrite the existing partition table with Btrfs, run the following command:

# mkfs.btrfs /dev/sdX

For example, use /dev/sda rather than /dev/sda1. The latter would format an existing partition instead of replacing the entire partitioning scheme.

Install the boot loader like you would for a data storage device with a Master Boot Record. For example, in the case of GRUB:

# grub-install --recheck /dev/sdX

File system creation

A Btrfs file system can either be newly created or have one converted.

Creating a new file system

File system on a single device

To format a partition do:

# mkfs.btrfs -L mylabel /dev/partition

The Btrfs default blocksize is 16KB. To use a larger blocksize for data/metadata, specify a value for the nodesize via the -n switch as shown in this example using 16KB blocks:

# mkfs.btrfs -L mylabel -n 16k /dev/partition

Multi-device file system

Multiple devices can be entered to create a RAID. Supported RAID levels include RAID 0, RAID 1, RAID 10, RAID 5 and RAID 6. The RAID levels can be configured separately for data and metadata using the -d and -m options respectively. By default the data is striped (raid0) and the metadata is mirrored (raid1). See Using Btrfs with Multiple Devices for more information about how to create a Btrfs RAID volume as well as the manpage for mkfs.btrfs.

# mkfs.btrfs -d raid0 -m raid1 /dev/part1 /dev/part2 ...
Note: Mounting such a filesystem may result in all but one of the according .device-jobs getting stuck and systemd never finishing startup due to a bug in handling this type of filesystem.

See RAID for advice on maintenance specific to multi-device Btrfs file systems.

Converting a file system from Ext3/4

Warning: As of mid-to-late 2015, there are many reports on the btrfs mailing list about incomplete/corrupt/broken conversions. The situation is improving as patches are being submitted, but proceed very carefully. Make sure you have working backups of any data you cannot afford to lose. See Conversion from Ext3 on the btrfs wiki.

Boot from an install CD, then convert by doing:

# btrfs-convert /dev/partition

Mount the partion and test the conversion by checking the files. Be sure to change the /etc/fstab to reflect the change (type to btrfs and fs_passno [the last field] to 0 as Btrfs does not do a file system check on boot). Also note that the UUID of the partition will have changed, so update fstab accordingly when using UUIDs. chroot into the system and rebuild the GRUB menu list (see Install from existing Linux and GRUB articles). If converting a root filesystem, while still chrooted run mkinitcpio -p linux to regenerate the initramfs or the system will not successfully boot. If you get stuck in grub with 'unknown filesystem' try reinstalling grub with grub-install /dev/partition and regenerate the config as well grub-mkconfig -o /boot/grub/grub.cfg.

After confirming that there are no problems, complete the conversion by deleting the backup ext2_saved sub-volume. Note that you cannot revert back to ext3/4 without it.

# btrfs subvolume delete /ext2_saved

Finally balance the file system to reclaim the space.

Configuring the file system

Copy-On-Write (CoW)

By default, Btrfs uses Wikipedia:copy-on-write for all files all the time. See the Btrfs Sysadmin Guide section] for implementation details, as well as advantages and disadvantages.

Disabling CoW

To disable copy-on-write for newly created files in a mounted subvolume, use the nodatacow mount option. This will only affect newly created files. Copy-on-write will still happen for existing files.

To disable copy-on-write for single files/directories do:

$ chattr +C /dir/file

This will disable copy-on-write for those operation in which there is only one reference to the file. If there is more than one reference (e.g. through cp --reflink=always or because of a filesystem snapshot), copy-on-write still occurs.

Note: From chattr man page: "For btrfs, the 'C' flag should be set on new or empty files. If it is set on a file which already has data blocks, it is undefined when the blocks assigned to the file will be fully stable. If the 'C' flag is set on a directory, it will have no effect on the directory, but new files created in that directory will have the No_COW attribute."
Tip: In accordance with the note above, you can use the following trick to disable copy-on-write on existing files in a directory:
$ mv /path/to/dir /path/to/dir_old
$ mkdir /path/to/dir
$ chattr +C /path/to/dir
$ cp -a /path/to/dir_old/* /path/to/dir
$ rm -rf /path/to/dir_old

Make sure that the data are not used during this process. Also note that mv or cp --reflink as described below will not work.

Forcing CoW

To force copy-on-write when copying files use:

$ cp --reflink source dest 

This would only be required if CoW was disabled for the file to be copied (as implemented above). See the man page on cp for more details on the --reflink flag.

Compression

Btrfs supports transparent compression, meaning every file on the partition is automatically compressed. This not only reduces the size of files, but also improves performance, in particular if using the lzo algorithm, in some specific use cases (e.g. single thread with heavy file IO), while obviously harming performance on other cases (e.g. multithreaded and/or cpu intensive tasks with large file IO).

Compression is enabled using the compress=zlib or compress=lzo mount options. Only files created or modified after the mount option is added will be compressed. However, it can be applied quite easily to existing files (e.g. after a conversion from ext3/4) using the btrfs filesystem defragment -calg command, where alg is either zlib or lzo. In order to re-compress the whole file system with lzo, run the following command:

# btrfs filesystem defragment -r -v -clzo /
Tip: Compression can also be enabled per-file without using the compress mount option; simply apply chattr +c to the file. When applied to directories, it will cause new files to be automatically compressed as they come.

When installing Arch to an empty Btrfs partition, use the compress option when mounting the filesystem: mount -o compress=lzo /dev/sdxY /mnt/. During configuration, add compress=lzo to the mount options of the root file system in fstab.

Subvolumes

"A btrfs subvolume is not a block device (and cannot be treated as one) instead, a btrfs subvolume can be thought of as a POSIX file namespace. This namespace can be accessed via the top-level subvolume of the filesystem, or it can be mounted in its own right." [1]

Each Btrfs file system has a top-level subvolume with ID 5. It can be mounted as / (by default), or another subvolume can be mounted instead.

See the following links for more details:

Creating a subvolume

To create a subvolume:

# btrfs subvolume create /path/to/subvolume

Listing subvolumes

To see a list of current subvolumes under path:

# btrfs subvolume list -p path

Deleting a subvolume

To delete a subvolume:

# btrfs subvolume delete /path/to/subvolume

Attempting to remove the directory /path/to/subvolume without using the above command will not delete the subvolume.

Mounting subvolumes

Subvolumes can be mounted like file system partitions using the subvol=/path/to/subvolume or subvolid=objectid mount flags. For example, you could have a subvolume named subvol_root and mount it as /. One can mimic traditional file system partitions by creating various subvolumes under the top level of the file system and then mounting them at the appropriate mount points. Thus one can easily restore a file system (or part of it) to a previous state easily using #Snapshots.

Tip: Changing subvolume layouts is made simpler by not using the toplevel subvolume (ID=5) as / (which is done by default). Instead, consider creating a subvolume to house your actual data and mounting it as /.

See Snapper#Suggested filesystem layout, Btrfs SysadminGuide#Managing Snapshots, and Btrfs SysadminGuide#Layout for example file system layouts using subvolumes.

Mount options

When mounting subvolumes with subvol= several mount options are available. For example, mount options that affect #Compression or #Copy-On-Write (CoW) can be used.

See Btrfs Wiki Mount options and Btrfs Wiki Gotchas for more information. In addition to configurations that can be made during or after file system creation, the various mount options for Btrfs can drastically change its performance characteristics. As this is a file system that is still in active development, changes and regressions should be expected. See links in the #See also section for some benchmarks.

Warning: Specific mount options can disable safety features and increase the risk of complete file system corruption.

Changing the default sub-volume

The default sub-volume is mounted if no subvol= mount option is provided. To change the default subvolume, do:

# btrfs subvolume set-default subvolume-id /

where subvolume-id can be found by listing.

Note: After changing the default subvolume on a system with GRUB, you should run grub-install again to notify the bootloader of the changes. See this forum thread.
Warning: Changing the default subvolume with btrfs subvolume set-default will make the top level of the filesystem inaccessible when the default subvolume is mounted . Reference: Btrfs Wiki Sysadmin Guide.

Commit interval settings

The resolution at which data are written to the filesystem is dictated by Btrfs itself and by system-wide settings. Btrfs defaults to a 30 seconds checkpoint interval in which new data are committed to the filesystem. This is tuneable using mount options (see below)

System-wide settings also affect commit intervals. They include the files under /proc/sys/vm/* and are out-of-scope of this wiki article. The kernel documentation for them resides in Documentation/sysctl/vm.txt.

Checkpoint interval

Starting with Linux 3.12, users are able to change the checkpoint interval from the default 30 s to any value by appending the commit mount option in /etc/fstab for the btrfs partition.

LABEL=arch64 / btrfs defaults,noatime,ssd,compress=lzo,commit=120 0 0

SSD TRIM

A Btrfs filesystem will automatically free unused blocks from an SSD drive supporting the TRIM command.

More information about enabling and using TRIM can be found in Solid State Drives#TRIM.

Usage

Displaying used/free space

General linux userspace tools such as /usr/bin/df will inaccurately report free space on a Btrfs partition since it does not take into account space allocated for and used by the metadata. It is recommended to use /usr/bin/btrfs to query a Btrfs partition. Below is an illustration of this effect, first querying using df -h, and then using btrfs filesystem df:

$ df -h /
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda3       119G  3.0G  116G   3% /
$ btrfs filesystem df /
Data: total=3.01GB, used=2.73GB
System: total=4.00MB, used=16.00KB
Metadata: total=1.01GB, used=181.83MB

Notice that df -h reports 3.0GB used but btrfs filesystem df reports 2.73GB for the data. This is due to the way Btrfs allocates space into the pool. The true disk usage is the sum of all three 'used' values which is inferior to 3.0GB as reported by df -h.

Note: If you see an entry of type unknown in the output of btrfs filesystem df at kernel >= 3.15, this is a display bug. As of this patch, the entry means GlobalReserve, which is kind of a buffer for changes not yet flushed. This entry is displayed as unknown, single in RAID setups and is not possible to re-balance.

Another useful command to show a less verbose readout of used space is btrfs filesystem show:

# btrfs filesystem show /dev/sda3

The newest command to get information on free/used space of a is btrfs filesystem usage:

# btrfs filesystem usage
Note: The btrfs filesystem usage command does not currently work correctly with RAID5/RAID6 RAID levels.

Defragmentation

Btrfs supports online defragmentation. To defragment the metadata of the root folder:

# btrfs filesystem defragment /

This will not defragment the entire file system. For more information read this page on the Btrfs wiki.

To defragment the entire file system verbosely:

# btrfs filesystem defragment -r -v /

Scrub

The Btrfs Wiki Glossary says that Btrfs scrub is "[a]n online filesystem checking tool. Reads all the data and metadata on the filesystem, and uses checksums and the duplicate copies from RAID storage to identify and repair any corrupt data."

# btrfs scrub start /
# btrfs scrub status /
Warning: The running scrub process will prevent the system from suspending, see this thread for details.

The btrfs-progs package brings the btrfs-scrub@.timer unit for monthly scrubbing the specified mountpoint. Enable the timer with an encoded path, e.g. btrfs-scrub@-.timer for / and btrfs-scrub@home.timer for /home.

You can also run the scrub manually by starting btrfs-scrub@.service (with the same encoded path). The advantage of this over # btrfs scrub is that the results of the scrub will be logged in the systemd journal.

Balance

"A balance passes all data in the filesystem through the allocator again. It is primarily intended to rebalance the data in the filesystem across the devices when a device is added or removed. A balance will regenerate missing copies for the redundant RAID levels, if a device has failed." [2] See Upstream FAQ page.

# btrfs balance start /
# btrfs balance status /

RAID

Btrfs offers native "RAID" for #Multi-device file systems. Notable features which set btrfs RAID apart from mdadm are self-healing redundant arrays and online balancing. See the Btrfs wiki page for more information. The Btrfs sysadmin page also has a section with some more technical background.

Snapshots

"A snapshot is simply a subvolume that shares its data (and metadata) with some other subvolume, using btrfs's COW capabilities." See Btrfs Wiki SysadminGuide#Snapshots for details.

To create a snapshot:

# btrfs subvolume snapshot source [dest/]name

To create a readonly snapshot add the -r flag. To create writable version of a readonly snapshot, simply create a snapshot of it.

Note: Snapshots are not recursive. Every sub-volume inside sub-volume will be an empty directory inside the snapshot.

Send/receive

A subvolume can be sent to stdout or a file using the send command. This is usually most useful when piped to a Btrfs receive command. For example, to send a snapshot named /root_backup (perhaps of a snapshot you made of / earlier) to /backup you would do the following:

 # btrfs send /root_backup | btrfs receive /backup

The snapshot that is sent must be readonly. The above command is useful for copying a subvolume to an external device (e.g., a USB disk mounted at /backup above).

You can also send only the difference between two snapshots. For example, if you have already sent a copy of root_backup above and have made a new readonly snapshot on your system named root_backup_new, then to send only the incremental difference to /backup do:

 # btrfs send -p /root_backup /root_backup_new | btrfs send /backup

Now a new subvolume named root_backup_new will be present in /backup.

See Btrfs Wiki's Incremental Backup page on how to use this for an incremental backup and for tools that automate the process.

Limitations

A few limitations should be known before trying.

Encryption

Btrfs has no built-in encryption support, but this may come in future. Users can encrypt the partition before running mkfs.btrfs. See dm-crypt/Encrypting an entire system#Btrfs subvolumes with swap.

Existing Btrfs file systems can use something like EncFS or TrueCrypt, though perhaps without some of Btrfs' features.

Swap file

Btrfs does not yet support swap files. This is due to swap files requiring a function that Btrfs does not have for possibility of file system corruption [3]. Patches for swapfile support are already available [4] and may be included in an upcoming kernel release. As an alternative a swap file can be mounted on a loop device with poorer performance but will not be able to hibernate. Install the package systemd-swap from the official repositories to automate this.

Linux-rt kernel

As of version 3.14.12_rt9, the linux-rt kernel does not boot with the Btrfs file system. This is due to the slow development of the rt patchset.

Tips and tricks

See Btrfs - Tips and tricks.

Troubleshooting

See the Btrfs Problem FAQ for general troubleshooting.

GRUB

Partition offset

Note: The offset problem may happen when you try to embed core.img into a partitioned disk. It means that it is OK to embed grub's corg.img into a Btrfs pool on a partitionless disk (e.g. /dev/sdX) directly.

GRUB can boot Btrfs partitions however the module may be larger than other file systems. And the core.img file made by grub-install may not fit in the first 63 sectors (31.5KiB) of the drive between the MBR and the first partition. Up-to-date partitioning tools such as fdisk and gdisk avoid this issue by offsetting the first partition by roughly 1MiB or 2MiB.

Missing root

Users experiencing the following: error no such device: root when booting from a RAID style setup then edit /usr/share/grub/grub-mkconfig_lib and remove both quotes from the line echo " search --no-floppy --fs-uuid --set=root ${hints} ${fs_uuid}". Regenerate the config for grub and the system should boot without an error.

BTRFS: open_ctree failed

As of November 2014 there seems to be a bug in systemd or mkinitcpio causing the following error on systems with multi-device Btrfs filesystem using the btrfs hook in mkinitcpio.conf:

BTRFS: open_ctree failed
mount: wrong fs type, bad option, bad superblock on /dev/sdb2, missing codepage or helper program, or other error

In some cases useful info is found in syslog - try dmesg|tail or so.

You are now being dropped into an emergency shell.

A workaround is to remove btrfs from the HOOKS array in /etc/mkinitcpio.conf and instead add btrfs to the MODULES array. Then regenerate the initramfs with mkinitcpio -p linux (adjust the preset if needed) and reboot.

See the original forums thread and FS#42884 for further information and discussion.

You will get the same error if you try to mount a raid array without one of the devices. In that case you must add the degraded mount option to /etc/fstab. If your root resides on the array, you must also add rootflags=degraded to your kernel parameters.

btrfs check

Warning: Since Btrfs is under heavy development, especially the btrfs check command, it is highly recommended to create a backup and consult the following Btfrs documentation before executing btrfs check with the --repair switch.

The btrfs check command can be used to check or repair an unmounted Btrfs filesystem. However, this repair tool is still immature and not able to repair certain filesystem errors even those that do not render the filesystem unmountable.

See Btrfsck for more information.

See also