btrfs is a fast-moving target. There are typically a great many bug fixes and enhancements between one kernel release and the next. Therefore:
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. Some distributions keep backports of recent kernels to earlier releases -- see the page below for details.
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.
Note also that btrfs is still considered experimental. While many people use it reliably, there are still problems being found.
Enterprise distributions with btrfs support
Since February 2012 there are two vendors who support btrfs in their distributions. They've put additional efforts to make btrfs supportable, so not everything written in the section above necessarily applies and it's recommended to ask the respective vendors about that.
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.
Many distros already enable Btrfs support in their kernels and have packages for the Btrfs userspace utilities. These are summarised in the table below. Versions marked in green, bold are recommended. Versions marked in red, italic are considered unreliable, dangerous, or obsolete.
|Distribution||Release||Kernel||btrfs tools||support in initrd||more information|
|Arch||3.12.7||3.12 2013-11-27||Install tools package, see wiki||Arch wiki|
|Debian||Unstable/sid||3.12.6||btrfs-tools 3.12 2014-01-01||Install tools package||Debian support|
|Debian||Testing/jessie||3.12||btrfs-tools 0.19 2013-07-05||Install tools package||Debian support|
|Debian||Stable/wheezy||3.2||btrfs-tools 0.19 2012-03-28||Install tools package||Debian support|
|Debian||Oldstable/squeeze||3.2 from backports||btrfs-tools 0.19 2010-06-01||Install tools package||Debian support|
|Fedora||F20||3.12.8||btrfs-progs 3.12 (1.fc20 2013-11-26)||?||Fedora support|
|Fedora||F19||3.12.8||btrfs-progs 3.12 (1.fc19 2013-11-26)||?||Fedora support|
|Gentoo||Stable||3.10||btrfs-progs 3.12~r1 (?)||?||Gentoo ebuilds|
|Gentoo||Unstable||3.12.8||btrfs-progs 3.12-r1||?||Gentoo ebuilds|
|openSUSE||13.1||3.11.6||3.12 2013-12-02||Install tools package||OpenSuSE support|
|SLES||11 SP2||3.0.x + backports||0.19 2012-01-27||+ (not for /boot)||Release Notes|
|Ubuntu||13.04 (Raring Ringtail)||3.8||btrfs-tools 0.19 2013-01-17||Install tools package||Ubuntu support|
|Ubuntu||12.10 (Quantal Quetzal)||3.5||btrfs-tools 0.19 2012-03-28||Install tools package||Ubuntu support|
|Ubuntu||12.04 LTS (Precise Pangolin)||3.2||btrfs-tools 0.19 2010-06-01||?||Ubuntu support|
|Ubuntu||11.10 (Oneiric Ocelot)||3.0||btrfs-tools 0.19 2010-06-01||?||Ubuntu support|
|Ubuntu||11.04 (Natty Narwhal)||2.6.38||btrfs-tools 0.19 2010-06-01||?||Ubuntu support|
|Ubuntu||10.10 (Maverick Meerkat)||2.6.35||btrfs-tools 0.19 2010-06-01||?||Ubuntu support|
|Ubuntu||10.04 LTS (Lucid Lynx)||2.6.32||btrfs-tools 0.19 (unknown date)||?||Ubuntu support|
|Ubuntu||9.10 (Karmic Koala)||btrfs-tools 0.8||?||Ubuntu support|
Btrfs is in a early development stage, though, which means that the latest stable kernel version will always have considerable improvements, so you are strongly encouraged to try the latest stable Linux kernel release or even the Btrfs development tree.
Compiling Btrfs from sources
Download the latest utility programs and modules following these instructions
For distribution-specific packages of the latest kernel or tools, please see the support links in the table above.
Compiling the kernel support
Btrfs uses libcrc32c in the kernel for file and metadata checksums and zlib to compress data. The necessary options are automatically selected when you select to compile btrfs: CONFIG_LIBCRC32C, CONFIG_ZLIB_INFLATE and CONFIG_ZLIB_DEFLATE.
Compiling the userspace utilities
The Btrfs utility programs require libuuid to build. This can be found in the e2fsprogs sources, and is usually available as libuuid, uuid-dev or e2fsprogs-devel from various distros. You also need the zlib development headers, usually available in a package called zlib-devel or zlib1g-dev.
Building the ext3 conversion tools requires libe2fs (usually available in e2fsprogs-devel or e2fslibs-dev) and libacl (may be available in libacl1-dev).
Building the utilities is just make. If you would also like the ext3 conversion program, type make convert.
make install will copy the programs into /usr/local/bin
Basic Filesystem Commands
Creating a filesystem of at least 1GiB is recommended.
- mkfs.btrfs: create a filesystem
- btrfs: control program to create snapshots and subvolumes and scan 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