Overview

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.

Btrfs is under heavy development, but every effort is being made to keep the filesystem stable and fast. Because of the speed of development, running the latest possible Linux kernel is highly recommended.

More Information on Btrfs is available at https://btrfs.wiki.kernel.org and http://en.wikipedia.org/wiki/Btrfs.

Recent benchmarks are available here https://btrfs.wiki.kernel.org/index.php/Main_Page#Benchmarking.

Features

• Extent based file storage
• 2^64 byte == 16 EiB maximum file size
• Space-efficient packing of small files
• Space-efficient indexed directories
• Dynamic inode allocation
• Writable snapshots, read-only snapshots
• Subvolumes (separate internal filesystem roots)
• Checksums on data and metadata
• Compression (gzip and LZO)
• Integrated multiple device support
  • File Striping, File Mirroring, and File Striping+Mirroring implementations
• Efficient incremental backup
• Background scrub process for finding and fixing errors on files with redundant copies
• Online filesystem defragmentation
• Offline filesystem check

Ubuntu-specific subvolume layout in 11.04 and later

In Ubuntu 11.04 and later, the installer sets up btrfs with a specific layout:

The default subvolume to mount is always the top of the btrfs tree (subvolid=5).

Subvolumes are created below the top of the btrfs tree as needed, e.g. for / and /home, it creates subvolumes named @ and @home. This means that specific options are needed in order to mount the subvolumes, instead of the default btrfs tree top:

• The @ subvolume is mounted to / using the kernel boot option rootflags=subvol=@

• The @home subvolume (if it is used), is mounted via the mount option subvol=@home in fstab.

How to work with snaphots in Ubuntu's layout

In order to work with snapshots of / or /home in the Ubuntu layout it is very convenient to mount the btrfs filesystem at a separate location, and work from the top of the btrfs tree, rather than from the mounted subvolumes.

sudo mount /dev/sdX# /mnt

Create snapshots

To create a snapshot use

sudo btrfs subvolume snapshot /mnt/@ /mnt/@_snapshot

this will create a snapshot of the @ subvolume named @_snapshot located also in the top of the btrfs tree.

Rollback to a snapshot

To roll back to a snapshot, you simply need to change its name to the name that ubuntu mounts, using

sudo mv /mnt/@ /mnt/@_badroot
sudo mv /mnt/@_snapshot /mnt/@

and reboot.

Delete a snapshot

To delete a snapshot use

sudo btrfs subvolume delete /mnt/@_badroot

btrfs snapshots are subvolumes in themselves, and self-contained, deleting the old @ subvolume like this is fine, provided we have a replacement.

The btrfs-tools command ''set-default'' will break Ubuntu's layout

Since Ubuntu is set up to always keep the top of the btrfs tree as the default mounting subvolume it will break when using the btrfs-tools command set-default, since this command is specifically designed to change the default mounting subvolume.

The mount options for / and /home described above relies on the fact that the corresponding subvolumes @ and @home can be located below the default mounting subvolume, and if set-default is used, this is no longer the case.

If you have accidentally used set-default and want to revert, you can do the following

sudo mount /dev/sdX# /mnt
sudo btrfs subvolume set-default 5 /mnt

since the id 5 is a permanent alias for the top of the btrfs tree.

Fresh Install on 11.04 Natty

As of 11.04, it is possible to use only btrfs file systems with the caveat that grub 'MUST NOT' be installed to the boot sector of the btrfs volume containing /boot. See also Ubuntu Grub2 Bug 757446 and Ubuntu Grub2 Bug 759772. You must install it to either the parent (sda rather than sda1; MBR/Reserved Sectors) 'OR' use a dedicated /boot partition as described in the forum post below.

When installing Ubuntu in one large btrfs-Partition without an extra boot-partition, take care to keep about 1 Mib space free at the beginning of the disk. This is possible using the partition manager in the Ubuntu installer. When there is not this space, the installer fails at the end when trying to install Grub!

Install as Root on earlier Ubuntu versions

Converting Ubuntu 12.10 ext4 root filesystem

Boot a Live CD with a recent kernel.

Open a terminal and run these commands:

sudo su

Check the filesystem for errors.

fsck.ext4 /dev/sda1
btrfs-convert /dev/sda1

Mount the filesystem and prepare the chroot.

mount /dev/sda1 /mnt
for i in dev dev/pts proc sys ; do mount --bind /$i /mnt/$i ; done
chroot /mnt

This displays the filesystem UUID. Copy it to the clipboard, or a piece of paper.

blkid | grep sda1

gedit /etc/fstab

Prepend the root filesystem line with a hash (#), to comment out it:

#UUID=1fe54331-f99a-4ef5-9bd4-a4fff6223e87 /               ext4    errors=remount-ro 0       1

Add a new line for the btrfs root, like the following:

# The root was converted to btrfs.
UUID=a74f5787-aee1-4981-b7e6-fbd3cb6ac919 /               btrfs    defaults 0       1

Remember to paste the UUID that was in the output of blkid. It is different from the previous one.

Be careful to remove the ext4 "errors=remount-ro" option, otherwise the boot will fail with error "Root filesystem check failed".

To prevent GRUB boot error "Sparse file not allowed", edit the file /etc/grub.d/00_header (see <http://askubuntu.com/a/105178/24432> for more info).

gedit /etc/grub.d/00_header

Prepend this line with a hash (#):

#if [ -n ${have_grubenv} ]; then save_env recordfail; fi

Now, we update grub.

grub-install /dev/sda # This prevents GRUB boot error "Unknown filesystem".
update-grub

Shutdown, remove the Live CD, reboot.

Instructional forum post link

Please see http://ubuntuforums.org/showpost.php?p=8716089&postcount=1

Managing Btrfs

Snapshots & Subvolumes

Create a subvolume:

btrfs subvolume create test

This creates a subvolume in your home area called test. It appears to be a directory.

Do a snapshot copy of a subvolume:

btrfs subvolume snapshot test snap-copy-one

This creates a subvolume in your home area called snap-copy-one complete with all the data contained in test at the time of the snapshot.

List your subvolume:

sudo btrfs subvolume list test

This lists your subvolumes. Root privileges and the name of one of your subvolumes is required.

Sample Output:

ID 264 top level 5 path home/myhome/test
ID 265 top level 5 path home/myhome/snap-copy-one

Delete your subvolume:

sudo btrfs subvolume delete test

Root privileges are required to delete subvolumes.

Adding Filesystem Compression

Edit /etc/fstab:

# <file system>                      <mount point>    <type>  <options>          <dump>  <pass>
proc                                        /proc  proc    nodev,noexec,nosuid   0  0
# / was on /dev/sda2 during installation
UUID=07e198ed-18a3-41ed-9e48-bde82ead65fc   /      btrfs   defaults, compress    0  1
# /boot was on /dev/sda1 during installation
UUID=90983817-83f8-464f-a50c-39cd02317447   /boot  ext2    defaults              0  2
# swap was on /dev/sda5 during installation
UUID=a3da3212-876f-4350-94b3-4b5b5040c871   none   swap    sw                    0  0

The compress option was added. Remount the filesystem using "sudo mount -o remount /" or simply reboot.

Compression algorithm:
Since kernel 2.6.38 you can choose between zlib (default) and lzo as compression algorithms. zlib has a higher compression ratio while lzo is faster and takes less cpu load. To use lzo you edit your fstab and add "compress=lzo" to your mount options as described above. Specifying "compress" equals "compress=zlib".

See Phoronix for a benchmark between zlib and lzo.

NOTE: Grub2 in 11.04 can't read lzo compressed root so you'll need a /boot partition to use it.

Display Filesystem Information

Show a device:

sudo btrfs filesystem show /dev/sda2

Displays information about device /dev/sda2.

Sample Output:

failed to read /dev/sr0
Label: none  uuid: 07e198ed-18a3-41ed-9e48-bde82ead65fc
        Total devices 1 FS bytes used 26.80GB
        devid    1 size 912.20GB used 28.27GB path /dev/sda2

Btrfs Btrfs v0.19

Show Filesystem Information for a path:

btrfs filesystem df /home/myhome

Displays information about path /home/myhome.

Sample Output:

Metadata: total=640.00MB, used=265.57MB
Data: total=27.00GB, used=26.54GB
System: total=12.00MB, used=12.00KB

Validate Filesystem Integrity

Fsck a device:

sudo btrfsck /dev/sda2

Does offline filesystem check of device /dev/sda2. Will not give sensible results for a mounted filesystem.

Sample Output:

found 28752076800 bytes used err is 0
total csum bytes: 27806792
total tree bytes: 277921792
total fs tree bytes: 233484288
btree space waste bytes: 76057148
file data blocks allocated: 35377807360
 referenced 28362235904
Btrfs Btrfs v0.19

Scrub a directory:

btrfs scrub Videos

Improve Filesystem Performance

Defragment a directory:

sudo btrfs filesystem defragment Videos

This only defragments the directory's index. The files within the directory are not affected. Files must be individually defragmented, e.g.:

sudo find Videos -exec btrfs filesystem defragment '{}' +

Spread data out evenly across the available devices

See https://btrfs.wiki.kernel.org/index.php/FAQ#What_does_.22balance.22_do.3F for what a balance actually does, and when it should be used.

btrfs filesystem balance /home/myhome

This operation could take some time.