btrfs provides a number of features (such as checksumming, snapshots, and subvolumes) that make it an excellent candidate for using it as the root partition in an Arch Linux installation. For a tour of btrfs features see A tour of btrfs. As is common with FLOSS, there are a number of ways to configure btrfs as the root filesystem.

This article assumes your are doing a fresh install from the Arch Linux installation media. It is also possible to create a backup of an existing Arch Linux installation and restore it to a fresh btrfs configuration. This technique is also shown in this article.

Note: This article is for more advanced Arch Linux users, but if you are a newbie and are one with the command line, you shouldn't have any trouble as long as you are determined.

Note: The btrfs_advanced mkinitcpio hook (provided by mkinitcpio-btrfs package) is needed specifically for rollback and possibly other advanced features. The standard btrfs hook is enough to get multi-device (RAID) support. The kernel is capable of booting a single-device btrfs root on its own.

Back up an existing Arch Linux installation

Tip: Skip this section if you are doing a fresh installation.

Having a complete backup strategy before messing with the partitioning of storage drives is vitally important. So before doing anything you must back up, and you must also know how to recover from a backup. There are of course a number of ways to do this. But the easiest by far is to mount a spare backup drive and use rsync:

Boot into a live image

It is recommended that you boot and install from the latest Archlinux Netinstall Image, or and up-to-date Archlinux installation, or Archboot. The latter is capable of installing to a btrfs partition natively but does not support the unified setup detailed here; it is however a good option for this procedure because it includes recent builds of all the necessary packages.

Preparing the root drive

Now it is time to actually install the btrfs filesystem. Please make sure that btrfs-progs is installed and functioning correctly:

Note: It is possible to allow btrfs to use the entire hard drive without using a partitioning scheme, but that is not recommended. [1]. The method used for the syslinux directions in this article does not use a partitioning system. This portion of the article will be updated in the future, but until then you can study the GUID Partition Table + syslinux installation method here.

Note: syslinux and GRUB2 allow booting from a drive without a separate boot partition. However, syslinux does not currently support boot directories within a btrfs subvolume. Both syslinux and GRUB2 allow the use of modern GPT partitioning.

GPT partitioning for GRUB2

GRUB2 requires a +2M boot partition at the front of the drive [2]. You can create that with gdisk:

# gdisk /dev/sda

Once gdisk has loaded, you can begin entering commands into the command prompt. Type ? to see the available commands. Press o to create a new partition table. Just use the help command and create two partitions and
then use p to verify the output:

Note: Notice the EF02 hex code for the partition type for the 2Mb GRUB2 boot partition. This is needed to allow GRUB2 to install the core.img file into that partition for booting

Once you have created the partitions, we will need to set the boot flag on the btrfs partition. Press x for advanced options and then press a to set attributes. Press the number for the partition you want to alter, in this
example it is 2. Now press 2 to set the legacy boot flag:

Note: If you are not using an SSD drive, remove discard,ssd from the mount options.

Now you should be in the newly mounted btrfs filesystem! If you plan on using the rollback features of btrfs, create a __snapshot directory for containing snapshots:

# mkdir __snapshot

Note: __snapshot is chosen for integration with current mkinitcpio-btrfsAUR. See the variable reference above, or the source mkinitcpio-btrfs package.

If you plan on using Syslinux as your boot loader, you will need to create a boot directory:

# mkdir boot

Note: Syslinux currently does not support boot directories within btrfs subvolumes. For this reason a boot directory must be created in the root directory of the btrfs filesystem and bound to a boot directory within the
subvolume.

Next we will create the subvolumes. To see all the commands available to manage subvolumes with btrfs:

# btrfs subvolume --help

To allow us to easily snapshot the root of our Arch Linux installation, it is recommended it be contained in a subvolume named __active:

Note: __active is chosen for integration with current mkinitcpio-btrfsAUR. See the variable reference above, or the source mkinitcpio-btrfs package.

# btrfs subvolume create __active && cd __active

Now we will create separate subvolumes for important FHS directories. This would allow us to monitor and adjust the size allocations for each subvolume:

Note: If you are not using an SSD drive, remove discard,ssd from the mount options.

And that's it! You should be ready to install a fresh copy of Arch Linux or restore from a backup. For example, if you made a tar backup with the techniques described above, simply:

# tar -xvpJf <backup_file> -C .

or if using rsync:

# rsync -avhHPS --exclude={dev,sys,proc,mnt,tmp,media} <backup_dir> .

btrfs and syslinux

In order to continue the installation (or restoration), boot in the root of the btrfs filesystem must be bound to the boot directory contained in the __active subvolume. First we should create a boot directory within the subvolume:

# mkdir /mnt/btrfs-active/boot

and then bind the two directories using mount:

# mount --bind /mnt/btrfs-root/boot /mnt/btrfs-active/boot

Installing the base system

The factual accuracy of this article or section is disputed.

Reason:please use the first argument of the template to provide a brief explanation. (Discuss in Talk:Mkinitcpio-btrfs#)

We will not be relying on AIF to do the install automatically and instead perform it manually.

Note: The AIF is no longer supported. Installing manually is now the official way. See the Installation Guide for more info

Note: You may need to uncomment a mirror from /mnt/btrfs-active/etc/pacman.d/mirrorlist, and/or make other adjustments to /mnt/btrfs-active/etc/pacman.conf.

Configuration

Once the you have successfully configured btrfs and installed (or recovered) your Arch Linux, it is important that we tweak some settings to get everything working together so when you reboot everything will work correctly.

/etc/fstab

This section has two different configurations depending on the bootloader you selected. We can begin by editing /mnt/btrfs-active/etc/fstab:

# nano /mnt/btrfs-active/etc/fstab

GRUB2

Add the following line, supplement <uuid> for the UUID of the btrfs root partition:

UUID=<uuid> / btrfs defaults,noatime,discard,ssd,subvol=__active 0 0

Note: If you are not using an SSD drive, remove discard,ssd from the mount options.

syslinux

Tip: Locations chosen for integration with upcoming release of mkinitcpio-btrfs

It is not necessary to add a subvol=XX option for /, as it must be handled by either the initramfs [btrfs_advanced] or via the kernel boot line [extlinux], and it may not be accurate anyways (e.g. rollback mode). subvolid=0 corresponds to the btrfs root, and guarantees it will always be mounted correctly, even if the default is changed.

You should now be able to reboot into grub, provided there were no problems encountered doing the steps above.

Syslinux

Syslinux now has an automatic installer that creates the necessary folders, sets bootflags, installs MBR etc. See Syslinux#Automatic_Install for more info. Make sure you have /mnt bind mounted then run:

If you ARE using the mkinitcpio hook, remove rootflags=subvol=__active from the APPEND line.

Final configuration

Almost done... be sure to edit /mnt/etc/rc.conf, set the root password, and similar. Good luck on reboot!

# reboot

Known issues

Rollback support

Rollback support, while fully functional, currently has one important caveat... it cannot handle kernel rollbacks because the kernel is not a part of the snapshot. This is due to the limitations of the bootloader described above. Until bootloaders support subvolumes, you must remember to manually back up your kernel + initramfs before a snapshot. Upcoming releases of mkinitcpio-btrfsAUR will attempt to address this shortcoming.

syslinux

syslinux operates successfully through times, but sometimes fails.

Installing syslinux with compression enabled, or editing the configuration file after enabling compression, causes boot to fail because syslinux cannot read compressed files. This probably also affects installing a new kernel with btrfs enabled but I haven't tested this.

Slow meta-data after installation

Do a defragmentation of / after the installation is done to fix the slow metadata issue. (a simple ls may take seconds)