Multiple devices can be entered to create a RAID. Supported RAID levels include RAID 0, RAID 1, RAID 10, RAID 5 and RAID 6. 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. By default the metadata is mirrored and data is striped. See [https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices Btrfs Wiki Using Btrfs with Multiple Devices] for more information.

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.

Installation

Btrfs is included in the default kernel and its tools (btrfs-progs) are available in the official repositories. GRUB, mkinitcpio, and Syslinux have support for Btrfs and require no additional configuration.

Additional packages

btrfs-progs includes btrfsck, a tool that can fix errors on Btrfs filesystems.

General administration of Btrfs

Creating a new file system

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

To format a partition do:

# mkfs.btrfs -L mylabel /dev/partition

Note: As of this commit (November 2013), Btrfs default blocksize is 16KB.

To use a larger blocksize for data/meta data, specify a value for the leafsize via the -l switch as shown in this example using 16KB blocks:

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

Multiple devices can be entered to create a RAID. Supported RAID levels include RAID 0, RAID 1, RAID 10, RAID 5 and RAID 6. By default the metadata is mirrored and data is striped. See Btrfs Wiki Using Btrfs with Multiple Devices for more information.

# mkfs.btrfs [options] /dev/part1 /dev/part2

Convert from Ext3/4

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).

To complete, delete the saved image, delete the sub-volume that image is on, and finally balance the file system to reclaim the space.

Btrfs on a HDD for archival purposes with an emphasis on maximizing space.

rw,relatime,compress-force=zlib,autodefrag

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:

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.

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

Limitations

Encryption

Btrfs has no built-in encryption support (this may come in future); users can encrypt the partition before running mkfs.btrfs. See dm-crypt.

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

Swap file

Btrfs does not support swap files. This is due to swap files requiring a function that Btrfs doesn't have for possibility of corruptions.link 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 systemd-loop-swapfileAUR.

GRUB

Partition offset

The factual accuracy of this article or section is disputed.

Reason: This may no longer be needed. Need to verify with a direct installation of Btrfs without a partition table. (Discuss in Talk:Btrfs#)

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 partitions tools such as fdisk and gdisk avoid this issue by offsetting the first partition by roughly 1MiB.

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.

Features

Various features are available and can be adjusted.

Copy-On-Write (CoW)

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 patched version of fs/btrfs/disk-io.c. On 01-Aug-2013, David Sterba submitted this patch to make this a formal mount time tuneable.

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.

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.

One can disable CoW for the entire block device by mounting it with nodatacow option. However, this will disable CoW for the entire file system.

To disable CoW for single files/directories do:

$ chattr +C /dir/file

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 CoW on existing files in a directory:

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

Likewise, to save space by forcing CoW when copying files use:

$ cp --reflink sourcedest

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 cp --reflink=auto.

Multi-device filesystem and RAID feature

Multi-device filesystem

When creating a btrfs filesystem, one can pass many partitions or disk devices to mkfs.btrfs. The filesystem will be created across these devices. One can "pool" this way, multiple partitions or devices to get a big btrfs filesystem.

One can also add or remove device from an existing btrfs filesystem (caution is mandatory).

A multi-device btrfs filesystem (also called a btrfs volume) is not recognized until btrfs device scan has been run. This is the purpose of the btrfs mkinitcpio hook.

RAID features

When creating multi-device filesystem, one can also specify to use RAID0, RAID1, RAID10, RAID5 or RAID6 across the devices comprising 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 works in block-pairs for raid0, raid1, and raid10. This means:

raid0 - block-pair stripped across 2 devices

raid1 - block-pair written to 2 devices

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.

For example:

Three 1TB disks in an md based raid1 yields a /dev/md0 with 1TB free space and the ability to safely lose 2 disks without losing data.

Three 1TB disks in a Btrfs volume with data=raid1 will allow the storage of approximately 1.5TB of data before reporting full. Only 1 disk can safely be lost without losing 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 the BTRFS FAQ for more info.

Sub-volumes

Creating sub-volumes

To create a sub-volume:

# btrfs subvolume create subvolume-name

Listing sub-volumes

To see a list of current sub-volumes:

# btrfs subvolume list -p .

Setting a default sub-volume

Warning: Changing the default subvolume with btrfs subvolume default will make the top level of the filesystem inaccessible, except by use of the subvolid=0 mount option. Reference: Btrfs Wiki Sysadmin Guide.

The default sub-volume is mounted if no subvol= mount option is provided.

Warning: When using legacy BIOS booting, syslinux is not capable of booting from a btrfs subvolume with the following setup, one must always use GRUB. (It is possible with a different, more complicated btrfs subvolume setup, that is out of the scope of this section.)

For increased flexibility, install the system into a dedicated sub-volume.
Set up a btrfs filesystem as to your liking and mount it to /mnt. The following mkfs command is given as an example.

# mkfs.btrfs /dev/sda1
# mount /dev/sda1 /mnt

Create a subvolume for root, where rootvol is an arbitrary name. If you wish, create additional subvolumes at this step, for example to accommodate /home.

Compression

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 improves performance, in particular if using the 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 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, set the compress option after preparing the storage drive. Simply switch to another terminal (Ctrl+Alt+number), and run the following command:

# mount -o remount,compress=lzo /dev/sdXY /mnt/target

After the installation is finished, add compress=lzo to the mount options of the root file system in fstab.

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

Partitioning

Btrfs can occupy an entire data storage device and replace the MBR or GPT partitioning schemes. One can use subvolumes to simulate partitions. There are some limitations to this approach in single disk setups: