- Home
- Packages
- Forums
- Wiki
- Bugs
- AUR
- Download

# Mkinitcpio-btrfs

From ArchWiki
Warning: This article is completely redesigned as of today (October 25th 2013). I've stipped all (in my opinion) unnecessary or outdated information. In case there is something missing, you can find it in the history.

Summary
Installing on btrfs root Outlines a process for installing (or converting) Arch Linux to a btrfs root drive with syslinux or GRUB2.
Overview
In order to boot Arch Linux, a Linux-capable boot loader such as GRUB(2), Syslinux, LILO or GRUB Legacy must be installed to the Master Boot Record or the GUID Partition Table. The boot loader is responsible for loading the kernel and initial ramdisk before initiating the boot process.
Resources
Btrfs — Wikipedia
FAQ — Btrfs Wiki
GNU GRUB — GNU Project
Syslinux Website
GUID Partition Table — Wikipedia

Btrfs provides a number of features that make it an excellent candidate for using it as the root partition in an Arch Linux installation:

- instant snapshots
- non-volatile rollback support
- integrated multi-device support RAID
- online resize, add/remove devices, defragmentation
- online fsck, checksumming and auto-correction

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.

Note: This article is an extension of the Official Arch Linux Install Guide. It asumes you have gained an overview on the general process of installing Arch Linux and will not provide back references to this guide.
Note: Arch's default mkinitcpio package contains a standard btrfs hook, which is enough to get multi-device (RAID) support. Beside that, the kernel is capable of booting a single-device btrfs root without any hook.

## mkinitcpio-btrfs

First of all you need to decide, if you want to use some of Btrfs's neat features like non-volatile rollback or automatic mounting of degraded Btrfs multi-device (RAID) volumes. To enable this features you need a special package from the Arch User Repository called mkinitcpio-btrfs. The package integrates some helpers in your boot process, to handle these features correctly.

This guide can also be followed without this package, through I generally recommend it. The relevant sections contain notes for both types of setup.

## Prerequisites

Boot up your Arch Linux installation media and configure your network connection if not done automatically.

## btrfs-progs

To create a btrfs filesystem you will need to install the btrfs-progs from Official Repositories. This package is normally present on your installation media. It is still a good idea to perform an update, to make sure you have the latest version of it.

## Partition disks

Partition your drive as you prefer. Both (GPT and MBR) partition tables are supported. If you want do encrypt your Btrfs, use dm-crypt.

Btrfs has build-in RAID support. Setting up at least RAID1 is recommended for enabling its internal selfhealing features. If you don't have two drives, setup two partitions of the same size on one drive.

Warning: If you want true non-volatile rollback support you MUST NOT create a separate `/boot` partition, as this will prevent rollback of your kernel.
Note: Having boot on a different partition in not supported with mkinitcpio-btrfs >= 0.4. This is because, kexec is used to reload the kernel from your root partition to make sure it is rolled back too. If you want, you can put it on a subvolume within your `__active` subvolume. Btrfs will automatically mount subvolume included in the currently mounted one.
Warning: If you need Swap support create a separate partition for it. DO NOT simply use a swap file! Doing so will slow down your btrfs filesystem.

## Format the partitions

Use `mkfs.btrfs` to create your root partition.

    # mkfs.btrfs -L root -m raid1 -d raid1 /dev/sda1 /dev/sdb1

## Mount the partitions

Now it is time to mount the new filesystem. First create the mount directory:

    # mount -o defaults,relatime,compress=lzo,ssd,discard /dev/sda1 /mnt

Note: If you are not using an SSD drive, remove `ssd,discard` from the mount options.
Note: Compression improves performance, since btrfs frequently writes its trees to the disk. The CPU usage needed for that is not worth mentioning. Allowed compression methods are lzo and gzip.

### Configure the btrfs filesystem

Clone the btrfs root to an `__active` subvolume for your future system root directory `/`. This will enable you to take snapshots in a directory outside of your system root and helps keeping a clean filesystem structure.

    # cd /mnt
    # btrfs subvolume snapshot . __active

If you plan on using the rollback features of btrfs, create a `__snapshot` directory for containing snapshots.

    # cd /mnt
    # mkdir __snapshot

Note: The subvolume and folder names are chosen for integration with current mkinitcpio-btrfs. You can also use different subvolume and folder names and specify them in `/etc/default/btrfs_advanced` later.

You can create separate subvolumes for important FHS directories. This would allow you to monitor and adjust the size allocations for each subvolume using `btrfs quota`:

    # cd /mnt/__active
    # btrfs subvolume create home
    # btrfs subvolume create var
    # btrfs subvolume create usr

To see your handy work:

    # btrfs subvolume list -p .

    ID 256 parent 5 top level 5 path __active
    ID 258 parent 256 top level 5 path __active/home
    ID 259 parent 256 top level 5 path __active/usr
    ID 260 parent 256 top level 5 path __active/var

Note: Child subvolumes are automatically mounted by Btrfs when the parent subvolume is mounted. This makes mounting extremely easy at boot time.

Btrfs supports to set a default subvolume, which is mounted if no `subvol=` option is provided at mount time. If you plan to use mkinitcpio-btrfs later on, you MUST set this default subvolume to your `__active` subvolume.

    # btrfs subvolume list .

    ID 256 gen 98 top level 5 path __active

    # btrfs subvolume set-default 256 .

Now that the subvolumes are created and we have a layout, lets mount the root subvolume directly:

    # cd
    # umount /mnt
    # mount -o defaults,relatime,compress=lzo,ssd,discard /dev/sda1 /mnt

Note: If you did not set the default subvolume you need to add an additional `subvol=__active` mount option.
Note: If you are not using an SSD drive, remove `ssd,discard` from the mount options.
Note: Compression improves performance, since btrfs frequently writes its trees to the disk. The CPU usage needed for that is not worth mentioning. Allowed compression methods are lzo and gzip.

## Install the base system

Proceed with bootstrap. If you plan to use mkinitcpio-btrfs, add its dependencys btrfs-progs and kexec-tools. You'll also need base-devel to build the package from AUR. And add your favorite boot loader to the `pacstrap` command too.

    # pacstrap /mnt base base-devel btrfs-progs kexec-tools grub

If you plan to use mkinitcpio-btrfs download its tarball to your chroot environment.

    # wget -O /mnt/root/mkinitcpio-btrfs.tar.gz https://aur.archlinux.org/packages/mk/mkinitcpio-btrfs/mkinitcpio-btrfs.tar.gz

## Configure the system

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

Create a place where you mount the Btrfs root subvolume to create snapshots later.

    # mkdir /var/lib/btrfs

### /etc/fstab

    # nano /mnt/etc/fstab

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

    UUID=<uuid>  /               btrfs  defaults,relatime,compress=lzo,ssd,discard             0  0
    UUID=<uuid>  /var/lib/btrfs  btrfs  defaults,relatime,compress=lzo,ssd,discard,subvolid=0  0  0

Note: If you did not set the default subvolume you need to add an additional `subvol=__active` mount option.
Note: If you are not using an SSD drive, remove `ssd,discard` from the mount options.
Note: Compression improves performance, since btrfs frequently writes its trees to the disk. The CPU usage needed for that is not worth mentioning. Allowed compression methods are lzo and gzip.
Note: Optional bind an empty folder over the `/var/lib/btrfs/__active` folder to prevent apps such as 'find' from complaining of any loops.

    /var/lib/btrfs/empty  /var/lib/btrfs/__active  none  bind  0  0

### mkinitcpio-btrfs

To install mkinitcpio-btrfs you need to extract the AUR package and build it.

    # cd /root
    # tar -zxvf mkinitcpio-btrfs.tar.gz
    # cd mkinitcpio-btrfs
    # makepkg -i --asroot

After installation, modify `/etc/default/btrfs_advanced` to your needs. And don't forget to add `btrfs-advanced` to your `HOOKS` variable in `/etc/mkinitcpio.conf`.

Note: You can savely remove `fsck` from your `HOOKS` variable, because Btrfs has a online fsck feature, and therefore doesn't provide an fsck module.

Now regenerate your initial RAM-disk.

    # mkinitcpio -p linux

## Install and configure a bootloader

Now proceed with installing your bootloader.

### GRUB

Note: To see all your boot messages I recommend to remove the `silent` option from `GRUB_CMDLINE_LINUX_DEFAULT` in `/etc/default/grub`. To prevent tty1 to flush all boot messages before printing the login prompt, edit `/etc/systemd/system/getty.target.wants/getty@tty1.service` and change `TTYVTDisallocate` to `no`.

Grub is able to boot directly from Btrfs root. So just do the usual installation steps.

Note: To have your multi-device Btrfs boot if your first device has failed, add the bootloader to the second device too.

    # grub-install --target=i386-pc --recheck /dev/sda
    # grub-install --target=i386-pc --recheck /dev/sdb
    # cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo
    # grub-mkconfig -o /boot/grub/grub.cfg

Make sure that your Btrfs root is correctly added to the kernel commandline in `/boot/grub/grub.cfg`. Using UUIDs for device identification is especially useful for multi-device (RAID) setups, because all Btrfs devices own the same UUID.

    root=UUID=fd88d586-bb4c-4fc7-81a6-f675e2829581

Warning: If you've set the default subvolume you MUST NOT add `subvol=__active` to your `rootflags`.
Note: Having boot on a different partition in not supported with mkinitcpio-btrfs >= 0.4. This is because, kexec is used to reload the kernel from your root partition to make sure it is rolled back too. If you want, you can put it on a subvolume within your `__active` subvolume. Btrfs will automatically mount subvolume included in the currently mounted one.

### Syslinux EFI

To boot from Btrfs using syslinux EFI, you need to setup up a dedicated EFI partition in `/boot/efi`. This partition needs to be formated as FAT32 (or HPFS on MacBooks). You need to set up your Syslinux directories on that special partition as described in Syslinux.

Warning: The downside of this setup is, that you need to store a working kernel image and its initrd on the EFI partition, because Syslinux can not access Btrfs filesystems directly. mkinitcpio-btrfs will then mount your Btrfs root and reload the kernel from your Btrfs `/boot` directory.

In `/boot/efi/EFI/syslinux/syslinux.cfg` make sure your Btrfs root is correctly added to the `APPEND` line.

    APPEND root=UUID=978e3e81-8048-4ae1-8a06-aa727458e8ff rw

Warning: If you've set the default subvolume you MUST NOT add `subvol=__active` to your `APPEND` line.

## Usage Hints

To create a snapshot of your root filesystem execute:

    # cd /var/lib/btrfs
    # sudo btrfs subvolume snapshot __active __snapshot/[snapshot name]

Use `btrfs scrub` for periodic online filesystem checks:

    # sudo btrfs scrub start /
    # sudo btrfs scrub status /

## Known issues

If you use a multi device (RAID) setup, make sure you rebalance after system upgrades, to prevent kernel panic on device failure:

    # sudo btrfs balance /

Retrieved from "https://wiki.archlinux.org/index.php?title=Mkinitcpio-btrfs&oldid=279654"
Category:

- Getting and installing Arch

## Navigation menu