Getting started
OBSOLETE CONTENT
This wiki has been archived and the content is no longer updated.
This guide will help you in setting up the btrfs filesystem and using it in your Linux system.
Contents |
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.
Distro support
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.
Enterprise distributions
Since February 2012, entrerprise distrubutions which support btrfs (including commercial support) are:
SUSE Enterprise Linux
With SLES11 SP2 comes support of btrfs, read more in the release notes section.
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.
Community distributions
- Debian support
- Fedora support
- Gentoo support
- Ubuntu support
- Arch support
- Funtoo support
- OpenSuSE support
Reporting problems
If you have a problem with btrfs, you should report it to either the Btrfs mailing list or to the libera.chat IRC channel.
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:
Partition | Filesystem | Start | End | Partition type |
---|---|---|---|---|
/dev/sda1 | (bootloader) | 0 | 4MiB | BIOS boot partition |
/dev/sda2 | Btrfs/FAT32* | 4MiB | 1GiB | EFI system partition |
/dev/sda3 | Swap | 1GiB | 4GiB | Swap partition |
/dev/sda4 | Btrfs | 4GiB | 100% | Linux filesystem |
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
Multiple devices
btrfs allows to create RAID consisting of multiple partitions or disks. See Using Btrfs with Multiple Devices for details and instructions.
btrfs (command)
btrfs is the control program for managing btrfs filesystems. It's most commonly used for operations like creating snapshots, creating subvolumes and scanning devices.
Examples:
- 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
Other tools
- 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
Further reading
- The Sysadmin's Guide to Btrfs
- Marc MERLIN's Btrfs talk at Linuxcon JP 2014 which gives an overview of Btrfs, best practices, and its more interesting features.