This guide will help you in setting up the btrfs filesystem and using it in your Linux system.
Before you start
btrfs is a fast-moving target. There are typically a great many bug fixes and enhancements between one kernel release and the next. Therefore:
Some distributions keep backports of recent kernels to earlier releases and it's a good idea to use them if you want to use btrfs.
If you are running a kernel two or more versions behind the latest one available from kernel.org, the first thing you will be asked to when you report a problem is to upgrade to the latest kernel.
Having the latest user-space tools are also useful, as they contain additional features and tools which may be of use in debugging or recovering your filesystem if something goes wrong.
The status of btrfs was experimental for a long time, but the the core functionality is considered good enough for daily use. There are new features being implemented and these should be considered experimental for a few releases when the bugs get ironed out when number of brave users help stabilizing it.
Many distros already enable Btrfs support in their kernels and have packages for the Btrfs userspace utilities, therefore we recommend to use them. Refer to your distro for more documentation about the specifics, like package names or versions available. This wiki is focused on upstream community and for general information.
Since February 2012, entrerprise distrubutions which support btrfs (including commercial support) are:
SUSE Enterprise Linux
Unbreakable Enterprise Kernel Release 2 for Oracle Linux
Available for both Oracle Linux 5 and 6, also available to Oracle Linux Customers from the Oracle Unbreakable Linux Network.
- Debian support
- Fedora support
- Gentoo support
- Ubuntu support
- Arch support
- Funtoo support
- OpenSuSE support
Creating a filesystem
Creating a filesystem of at least 1GiB is recommended.
btrfs as root fileystem
If you use a distro which supports btrfs, it's very likely that you decided to use btrfs as the root filesystem created during installation process. In that case, there procedure differs on each distribution and it's the best to follow their guides and rely on their installers.
As a general information, the recommended partition layout for an installation for a desktop workstation or a laptop with one drive is:
|/dev/sda1||(bootloader)||0||4MiB||BIOS boot partition|
|/dev/sda2||Btrfs/FAT32*||4MiB||1GiB||EFI system partition|
|1) Note that if you use EFI you need a FAT32 formatted EFI System Partition.|
2) If you have a very old GRUB, then it may not support Btrfs for /boot (/dev/sda2). In that case use Ext4
Creating new filesystems
If you want to create a new btrfs filesystem, you can use the mkfs.btrfs tool.
btrfs filesystems can be created on:
- partitions (example: /dev/sdb1)
- raw disks, without partitioning (example: /dev/sdb)
Below we refer to both of them as devices.
On single device
To create a btrfs filesystem on a single device, use the following command:
mkfs.btrfs -L mylabel /dev/disk
For example, on a partition:
mkfs.btrfs -L mylabel /dev/sdb1
Or on the full raw disk:
mkfs.btrfs -L mylabel /dev/sdb
btrfs allows to create RAID consisting of multiple partitions or disks. See Using Btrfs with Multiple Devices for details and instructions.
btrfs is the control program for managing btrfs filesystems. It's most commonly used for operations like creating snapshots, creating subvolumes and scanning devices.
- Scanning devices:
- Scan all devices looking for btrfs filesystems, or scan just one partition
btrfs device scan btrfs device scan /dev/sda
- Snapshots and subvolumes
- mount -t btrfs /dev/sda2 /mnt/btrfs
btrfs subvolume create /mnt/btrfs/new_subvol btrfs subvolume snapshot /mnt/btrfs /mnt/btrfs/snapshot_of_root
Now it is possible to mount the subvolumes
mount -t btrfs -o subvol=new_subvol /dev/sda2 /mnt/new_subvol mount -t btrfs -o subvol=snapshot_of_root /dev/sda2 /mnt/snap
- btrfsck: do a limited check of the FS extent trees.
- btrfs-debug-tree: print all of the FS metadata in text form
btrfs-debug-tree /dev/sda2 >& big_output_file
- If a problem occures you can create an image of the fs with btrfs-image and send it to the devs. (All data will be zeroed, but metadata and the like is preserved.)
btrfs-image -c 9 /dev/sda2 /tmp/btrfs_dump.z
- Mount options - list of mount options