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.
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.
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. 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.
Btrfs is under active development, the stable kernels receive bugfixes during the development phase of new version and should be safe to use. The distribution kernels do not necesessarily track the most recent kernels but probably backport important fixes.
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