Difference between revisions of "Mkinitcpio-btrfs"

From ArchWiki
Jump to: navigation, search
m (Visit moved page Installing on Btrfs root to Mkinitcpio-btrfs: As mentioned in discussion page. Updated content will follow.)
(Redesigned the page to match current state of Btrfs and make it compatible to the AUR package mkinitcpio-btrfs again.)
Line 1: Line 1:
{{deletion|reason=This page needs to be deleted. As of today (April 2013) no additional steps beyond those outlined in [[Installation_Guide]] are required to install Archlinux on Btrfs (except filesystem creation, ''mkfs.btrfs''). First, all entries regarding bootloader and partitioning are not specific to the Btrfs filesystem and shouldn't be here. Instead, future users should be redirected to their dedicated pages. Second, mkinitcpio-btrfs should have its own wiki page because it is not in the official repositories and it is not required to be part of the installation process.}}
+
{{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.}}
 +
 
 
[[Category:Getting and installing Arch]]
 
[[Category:Getting and installing Arch]]
 
{{Article summary start}}
 
{{Article summary start}}
Line 13: Line 14:
 
{{Article summary end}}
 
{{Article summary end}}
  
[[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 [http://www.youtube.com/watch?v=hxWuaozpe2I A tour of btrfs]. As is common with FLOSS, there are a number of ways to configure btrfs as the root filesystem.
+
[[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
  
This article assumes your are doing a fresh install from the [https://www.archlinux.org/download/ 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.
+
For a tour of btrfs features see [http://www.youtube.com/watch?v=hxWuaozpe2I A tour of btrfs]. As is common with FLOSS, there are a number of ways to configure btrfs as the root filesystem.
  
{{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.}}
+
This article assumes your are doing a fresh install from the [https://www.archlinux.org/download/ Arch Linux installation media].
  
== btrfs-progs ==
+
{{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.}}
  
To create a btrfs filesystem you will need to [[pacman|install]] the {{Pkg|btrfs-progs}} from [[Official Repositories]]. If using [[Archboot]], it's already available.
+
{{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 ==
 
== mkinitcpio-btrfs ==
  
To get rollback features on your btrfs root device, you will need to install the {{AUR|mkinitcpio-btrfs}} package from the [[Arch User Repository]].
+
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 {{AUR|mkinitcpio-btrfs}}. The package integrates some helpers in your boot process, to handle these features correctly.
  
For reference, here are the internal variables used by {{AUR|mkinitcpio-btrfs}}:
+
This guide can also be followed without this package, through I generally recommend it. The relevant sections contain notes for both types of setup.
  
${BTRFS_HAS_ROLLBACK:=true}
+
== Prerequisites ==
${BTRFS_BOOT_SUBVOL:="__active"}
+
${BTRFS_DIR_WORK:="/new_root"}
+
${BTRFS_DIR_SNAP:="/__snapshot"}
+
${BTRFS_DIR_ACTIVE:="/__active"}
+
${BTRFS_DIR_ROLLBACK:="/__rollback"}
+
${BTRFS_ROLLBACK_CHOICE:="default"}
+
${BTRFS_ROLLBACK_LIST:="default"}
+
${BTRFS_ROLLBACK_LIST_COUNT:=0}
+
  
{{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.}}
+
Boot up your [https://www.archlinux.org/download/ Arch Linux installation media] and configure your network connection if not done automatically.
  
== Boot into a live image ==
+
== btrfs-progs ==
  
It is recommended that you boot and install from the latest [https://www.archlinux.org/download/ Archlinux Netinstall Image], or an 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.
+
To create a btrfs filesystem you will need to [[pacman|install]] the {{Pkg|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.
  
== Preparing the root drive ==
+
== Partition disks ==
  
Now it is time to actually install the btrfs filesystem. Please make sure that {{Pkg|btrfs-progs}} is installed and functioning correctly:
+
Partition your drive as you prefer. Both ([[GUID Partition Table|GPT]] and [[Master Boot Record|MBR]]) partition tables are supported. If you want do encrypt your Btrfs, use [[dm-crypt with LUKS|dm-crypt]].
  
# btrfs --help
+
Btrfs has [https://btrfs.wiki.kernel.org/index.php/UseCases#RAID 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|1=If you need swap support, either make a partition, or use the loop method detailed below. '''DO NOT''' simply use a swap file! [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=35054394c4b3cecd52577c2662c84da1f3e73525 Doing so will corrupt your btrfs filesystem].}}
+
{{Warning|If you want true non-volatile rollback support you '''MUST NOT''' create a separate {{ic|/boot}} partition, as this will prevent rollback of your kernel.}}
  
{{Note|It is possible to allow btrfs to use the entire hard drive without using a partitioning scheme, but that is not recommended. [[GRUB2#Install_to_partition_or_partitionless_disk]]. 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 [http://tincman.wordpress.com/2011/01/20/installing-arch-linux-onto-a-gpt-partitioned-btrfs-root-ssd-on-a-legacy-bios-system/ here].}}
+
{{Note|Having boot on a different partition in not supported with {{AUR|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 {{ic|__active}} subvolume. Btrfs will automatically mount subvolume included in the currently mounted one.}}
  
{{Warning| As of January 7,2012, Syslinux does not support multidevice btrfs root!!}}
+
{{Warning|If you need '''Swap''' support create a separate partition for it. '''DO NOT''' simply use a swap file! [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=35054394c4b3cecd52577c2662c84da1f3e73525 Doing so will slow down your btrfs filesystem].}}
  
{{Note|[[syslinux]] and [[GRUB2]] allow booting from a drive without a separate boot partition. Both syslinux and GRUB2 allow the use of modern GPT partitioning.}}
+
== Format the partitions ==
  
=== GPT partitioning for GRUB2 ===
+
Use {{ic|mkfs.btrfs}} to create your root partition.
  
To get started partitioning, we must [[pacman|install]] the {{Pkg|gptfdisk}} package from the [[Official Repositories]]:
+
# mkfs.btrfs -L root -m raid1 -d raid1 /dev/sda1 /dev/sdb1
  
# pacman -S gptfdisk
+
== Mount the partitions ==
  
[[GRUB2]] requires a +2M boot partition at the front of the drive [[GRUB2#GPT_specific_instructions]]. You can create that with gdisk:
+
Now it is time to mount the new filesystem. First create the mount directory:
  
  # gdisk /dev/sda
+
  # mount -o defaults,relatime,compress=lzo,ssd,discard /dev/sda1 /mnt
  
Once gdisk has loaded, you can begin entering commands into the command prompt. Type {{ic|?}} to see the available commands. Press {{ic|o}} to create a new partition table. Just use the help command and create two partitions and
+
{{Note|If you are not using an '''SSD drive''', remove {{ic|ssd,discard}} from the mount options.}}
then use {{ic|p}} to verify the output:
+
  
{{bc|
+
{{Note|'''Compression''' [http://www.phoronix.com/scan.php?page=article&item=btrfs_compress_2635&num=1 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 [http://www.phoronix.com/scan.php?page=article&item=btrfs_lzo_2638&num=1 lzo] and gzip.}}
GPT fdisk (gdisk) version 0.8.2
+
 
+
Partition table scan:
+
  MBR: protective
+
  BSD: not present
+
  APM: not present
+
  GPT: present
+
 
+
Found valid GPT with protective MBR; using GPT.
+
 
+
Command (? for help): p
+
Disk /dev/sda: 234441648 sectors, 111.8 GiB
+
Logical sector size: 512 bytes
+
Disk identifier (GUID): C75A01F9-D34E-4895-9AAB-2C8118118211
+
Partition table holds up to 128 entries
+
First usable sector is 34, last usable sector is 234441614
+
Partitions will be aligned on 2048-sector boundaries
+
Total free space is 2014 sectors (1007.0 KiB)
+
 
+
Number  Start (sector)    End (sector)  Size      Code  Name
+
  1            2048            6143  2.0 MiB    EF02  BIOS boot partition
+
  2            6144      234441614  111.8 GiB  8300  Linux filesystem
+
 
+
Command (? for help):
+
}}
+
 
+
{{Note|Notice the {{ic|EF02}} hex code for the partition type for the 2Mb GRUB2 boot partition. This is needed to allow GRUB2 to install the {{ic|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 {{ic|x}} for advanced options and then press {{ic|a}} to set attributes. Press the number for the partition you want to alter, in this
+
example it is {{ic|2}}. Now press {{ic|2}} to set the legacy boot flag:
+
 
+
{{bc|
+
Command (? for help): x
+
 
+
Expert command (? for help): a
+
Partition number (1-2): 2
+
Known attributes are:
+
0: system partition
+
1: hide from EFI
+
2: legacy BIOS bootable
+
60: read-only
+
62: hidden
+
63: do not automount
+
 
+
Attribute value is 0000000000000000. Set fields are:
+
  No fields set
+
 
+
Toggle which attribute field (0-63, 64 or <Enter> to exit): 2
+
Have enabled the 'legacy BIOS bootable' attribute.
+
Attribute value is 0000000000000004. Set fields are:
+
2 (legacy BIOS bootable)
+
 
+
Toggle which attribute field (0-63, 64 or <Enter> to exit):
+
}}
+
 
+
Finally, press {{ic|w}} to write the data to the disk.
+
 
+
=== GPT partitioning for Syslinux ===
+
 
+
This section hasn't been written yet. For a quick tutorial go [http://tincman.wordpress.com/2011/01/20/installing-arch-linux-onto-a-gpt-partitioned-btrfs-root-ssd-on-a-legacy-bios-system/ here];
+
  
 
=== Configure the btrfs filesystem ===
 
=== Configure the btrfs filesystem ===
  
With the drive partitioned and ready for a filesystem, make sure {{Pkg|btrfs-progs}} is installed and create the filesystem on the root partition:
+
Clone the btrfs root to an {{ic|__active}} subvolume for your future system root directory {{ic|/}}. This will enable you to take snapshots in a directory outside of your system root and helps keeping a clean filesystem structure.
 
+
# mkfs.btrfs -L btrfs-root /dev/sda2
+
 
+
Now it is time to mount the new filesystem. First create the mount directory:
+
 
+
# mkdir /mnt/btrfs-root
+
 
+
and mount the partition:
+
 
+
# mount -o defaults,noatime,discard,ssd /dev/sda2 /mnt/btrfs-root && cd /mnt/btrfs-root
+
  
{{Note|If you are not using an SSD drive, remove {{ic|discard,ssd}} from the mount options.}}
+
# cd /mnt
{{Note|I had performance problems (especially when suspending and halting) on my notebook with SSD. '''Disabling''' the '''discard''' option resolved the problem. [http://wiki.ubuntuusers.de/Btrfs-Mountoptionen#Verbotene-Mountoptionen]}}
+
# btrfs subvolume snapshot . __active
  
Now you should be in the newly mounted btrfs filesystem! If you plan on using the rollback features of btrfs, create a {{ic|__snapshot}} directory for containing snapshots:
+
If you plan on using the rollback features of btrfs, create a {{ic|__snapshot}} directory for containing snapshots.
  
 +
# cd /mnt
 
  # mkdir __snapshot
 
  # mkdir __snapshot
  
{{Note|{{ic|__snapshot}} is chosen for integration with current {{AUR|mkinitcpio-btrfs}}. See the variable reference above, or the source mkinitcpio-btrfs package.}}
+
{{Note|The subvolume and folder names are chosen for integration with current {{AUR|mkinitcpio-btrfs}}. You can also use different subvolume and folder names and specify them in {{ic|/etc/default/btrfs_advanced}} later.}}
  
If you plan on using [[Syslinux]] as your boot loader, you will need to create a boot directory:
+
You can create separate subvolumes for important [http://www.pathname.com/fhs/ FHS] directories. This would allow you to monitor and adjust the size allocations for each subvolume using {{ic|btrfs quota}}:
 
+
# 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 {{ic|__active}}:
+
 
+
{{Note|{{ic|__active}} is chosen for integration with current {{AUR|mkinitcpio-btrfs}}. 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 [http://www.pathname.com/fhs/ FHS] directories. This would allow us to monitor and adjust the size allocations for each subvolume:
+
  
 +
# cd /mnt/__active
 
  # btrfs subvolume create home
 
  # btrfs subvolume create home
 
  # btrfs subvolume create var
 
  # btrfs subvolume create var
Line 188: Line 101:
 
}}
 
}}
  
Fix the permissions:
+
{{Note|Child subvolumes are automatically mounted by Btrfs when the parent subvolume is mounted. This makes mounting extremely easy at boot time.}}
  
chmod 755 ../\__active var usr home
+
Btrfs supports to set a default subvolume, which is mounted if no {{ic|subvol&#61;}} option is provided at mount time. If you plan to use {{AUR|mkinitcpio-btrfs}} later on, you '''MUST''' set this default subvolume to your {{ic|__active}} subvolume.
  
Now that the subvolumes are created and we have a layout, lets mount the root subvolume directly:
+
{{hc|# btrfs subvolume list .|
 +
ID 256 gen 98 top level 5 path __active}}
  
  # mkdir /mnt/btrfs-active
+
  # btrfs subvolume set-default 256 .
# mount -o defaults,discard,noatime,ssd,subvol=__active /dev/sda2 /mnt/btrfs-active && cd /mnt/btrfs-active
+
  
{{Note|If you are not using an SSD drive, remove {{ic|discard,ssd}} from the mount options.}}
 
{{Note|I had performance problems (especially when suspending and halting) on my notebook with SSD. '''Disabling''' the '''discard''' option resolved the problem. [http://wiki.ubuntuusers.de/Btrfs-Mountoptionen#Verbotene-Mountoptionen]}}
 
  
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:
+
Now that the subvolumes are created and we have a layout, lets mount the root subvolume directly:
  
  # tar -xvpJf <backup_file> -C .
+
  # cd
 +
# umount /mnt
 +
# mount -o defaults,relatime,compress=lzo,ssd,discard /dev/sda1 /mnt
  
or if using rsync:
+
{{Note|If you did not set the default subvolume you need to add an additional {{ic|subvol&#61;__active}} mount option.}}
  
# rsync -avhHPS --exclude={dev,sys,proc,mnt,tmp,media} <backup_dir> .
+
{{Note|If you are not using an '''SSD drive''', remove {{ic|ssd,discard}} from the mount options.}}
  
=== btrfs and syslinux ===
+
{{Note|'''Compression''' [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_compress_2635&num&#61;1 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 [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_lzo_2638&num&#61;1 lzo] and gzip.}}
  
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 {{ic|__active}} subvolume. First we should create a boot directory within the subvolume:
+
== Install the base system ==
  
# mkdir /mnt/btrfs-active/boot
+
Proceed with bootstrap. If you plan to use {{AUR|mkinitcpio-btrfs}}, add its dependencys {{Pkg|btrfs-progs}} and {{Pkg|kexec-tools}}. You'll also need {{Pkg|base-devel}} to build the package from AUR. And add your favorite boot loader to the {{ic|pacstrap}} command too.
  
and then bind the two directories using mount:
+
# pacstrap /mnt base base-devel btrfs-progs kexec-tools grub
  
# mount --bind /mnt/btrfs-root/boot /mnt/btrfs-active/boot
+
If you plan to use {{AUR|mkinitcpio-btrfs}} download its tarball to your chroot environment.
  
== Installing the base system ==
+
# wget -O /mnt/root/mkinitcpio-btrfs.tar.gz https://aur.archlinux.org/packages/mk/mkinitcpio-btrfs/mkinitcpio-btrfs.tar.gz
 +
 +
== Configure the system ==
  
{{Accuracy}}
+
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.
  
We will not be relying on AIF to do the install automatically and instead perform it manually.
+
Create a place where you mount the Btrfs root subvolume to create snapshots later.
  
{{Note|The AIF is no longer supported. Installing manually is now the official way. See the [[Installation Guide]] for more info}}
+
  # mkdir /var/lib/btrfs
 
+
{{Note|You may need to uncomment a mirror from {{ic|/mnt/btrfs-active/etc/pacman.d/mirrorlist}}, and/or make other adjustments to {{ic|/mnt/btrfs-active/etc/pacman.conf}}.}}
+
 
+
Lets begin by creating the necessary directories:
+
 
+
  # mkdir -p dev proc sys var/lib/pacman
+
 
+
Now we bind the system directories to our installation directory:
+
 
+
# mount -o bind /dev dev/
+
# mount -t proc /proc proc/
+
# mount -t sysfs /sys sys/
+
 
+
Install base, btrfs-progs, and a bootloader (grub-bios, grub-efi, syslinux, etc). Switch {{ic|<boot_loader>}} to your preferred boot loader.
+
 
+
Also install base-devel to build mkinitcpio-btrfs from the AUR.
+
 
+
# pacman -r . -Sy base btrfs-progs mkinitcpio-btrfs <boot_loader> --ignore grub
+
 
+
=== 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 ===
 
=== /etc/fstab ===
  
This section has two different configurations depending on the bootloader you selected. We can begin by editing {{ic|/mnt/btrfs-active/etc/fstab}}:
+
  # nano /mnt/etc/fstab
 
+
  # nano /mnt/btrfs-active/etc/fstab
+
 
+
==== GRUB2 ====
+
  
 
Add the following line, supplement {{ic|<uuid>}} for the UUID of the btrfs root partition:
 
Add the following line, supplement {{ic|<uuid>}} for the UUID of the btrfs root partition:
  
  UUID=<uuid> / btrfs   defaults,noatime,discard,ssd,subvol=__active 0 0
+
  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
  
{{Note|If you are not using an SSD drive, remove {{ic|discard,ssd}} from the mount options.}}
+
{{Note|If you did not set the default subvolume you need to add an additional {{ic|subvol&#61;__active}} mount option.}}
{{Note|I had performance problems (especially when suspending and halting) on my notebook with SSD. '''Disabling''' the '''discard''' option resolved the problem. [http://wiki.ubuntuusers.de/Btrfs-Mountoptionen#Verbotene-Mountoptionen]}}
+
  
==== Syslinux ====
+
{{Note|If you are not using an '''SSD drive''', remove {{ic|ssd,discard}} from the mount options.}}
  
{{Tip|Locations chosen for integration with upcoming release of mkinitcpio-btrfs}}
+
{{Note|'''Compression''' [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_compress_2635&num&#61;1 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 [http://www.phoronix.com/scan.php?page&#61;article&item&#61;btrfs_lzo_2638&num&#61;1 lzo] and gzip.}}
  
Add everything to {{ic|/mnt/btrfs-active/etc/fstab}} ... {{ic|(btrfs-root)/boot}} will be --bind mounted so kernel upgrades work:
+
{{Note|Optional bind an empty folder over the {{ic|/var/lib/btrfs/__active}} folder to prevent apps such as 'find' from complaining of any loops.}}
  
{{hc|/etc/fstab|2=
+
  /var/lib/btrfs/empty /var/lib/btrfs/__active none  bind 0  0
/dev/disk/by-label/btrfs-root  /                    btrfs  defaults,noatime,subvolid=0  0  0
+
/dev/disk/by-label/btrfs-root /var/lib/btrfs-root  btrfs  defaults,noatime            0  0
+
/var/lib/btrfs-root/boot      /boot                none  bind                        0 0
+
/var/lib/btrfs-root/empty/    /var/lib/btrfs-root/__active   none  bind               0  0}}
+
  
It is not necessary to add a {{ic|1=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). {{ic|1=subvolid=0}} corresponds to the btrfs root, and guarantees it will always be mounted correctly, even if the default is changed.
+
=== mkinitcpio-btrfs ===
  
Optional bind an empty folder over the {{ic|/var/lib/btrfs-root/__active}} folder to prevent apps such as 'find' from complaining of any loops.
+
To install {{AUR|mkinitcpio-btrfs}} you need to extract the AUR package and build it.
  
==== mkinitcpio-btrfs ====
+
# cd /root
 +
# tar -zxvf mkinitcpio-btrfs.tar.gz
 +
# cd mkinitcpio-btrfs
 +
# makepkg -i --asroot
  
Download the mkinitcpio-btrfs tarball:
+
After installation, modify {{ic|/etc/default/btrfs_advanced}} to your needs. And don't forget to add {{ic|btrfs-advanced}} to your {{ic|HOOKS}} variable in {{ic|/etc/mkinitcpio.conf}}.
  
# wget -O /mnt/btrfs-active/root/mkinitcpio-btrfs.tar.gz https://aur.archlinux.org/packages/mk/mkinitcpio-btrfs/mkinitcpio-btrfs.tar.gz
+
{{Note|You can savely remove {{ic|fsck}} from your {{ic|HOOKS}} variable, because Btrfs has a online fsck feature, and therefore doesn't provide an fsck module.}}
  
Add {{ic|btrfs_advanced}} to the {{ic|HOOKS}} section of {{ic|/mnt/btrfs-active/etc/mkinitcpio.conf}}:
+
Now regenerate your initial RAM-disk.
 
+
{{hc|# nano /mnt/btrfs-active/etc/mkinitcpio.conf|2=
+
...
+
HOOKS="[...] btrfs_advanced"
+
...}}
+
 
+
Once you've chroot'ed into the btrfs installation, first install mkinitcpio-btrfs:
+
 
+
# cd /root
+
# tar -xvzf mkinitcpio-btrfs.tar.gz
+
# cd mkinitcpio-btrfs
+
# makepkg
+
# pacman -U mkinitcpio-btrfs-${version}.pkg.tar.xz
+
 
+
Then rebuild the initramfs:
+
  
 
  # mkinitcpio -p linux
 
  # mkinitcpio -p linux
  
== Installing the bootloader ==
+
== Install and configure a bootloader ==
  
If everything went smoothly (when does it ever?), you should have the great pleasure of installing your bootloader into the mbr of your root drive.
+
Now proceed with installing your bootloader.
  
 
=== GRUB ===
 
=== GRUB ===
  
See [[GRUB]] for advanced instructions. Once you have GRUB configured, and you chrooted into your install directory, install the boot loader.
+
{{Note|To see all your boot messages I recommend to remove the {{ic|silent}} option from {{ic|GRUB_CMDLINE_LINUX_DEFAULT}} in {{ic|/etc/default/grub}}. To prevent tty1 to flush all boot messages before printing the login prompt, edit {{ic|/etc/systemd/system/getty.target.wants/getty@tty1.service}} and change {{ic|TTYVTDisallocate}} to {{ic|no}}.}}
  
Chroot:
+
Grub is able to boot directly from Btrfs root. So just do the usual installation steps.
  
If you decided that you liked your current Arch Linux and are restoring from a backup, you will need to chroot into your installation after doing all the necessary steps:
+
{{Note|To have your multi-device Btrfs boot if your first device has failed, add the bootloader to the second device too.}}
  
  # cp /etc/resolv.conf etc/
+
  # grub-install --target=i386-pc --recheck /dev/sda
  # mount -o bind /dev dev/
+
  # grub-install --target=i386-pc --recheck /dev/sdb
  # mount -o bind /dev/pts dev/pts
+
  # cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo
# mount -t proc /proc proc/
+
  # grub-mkconfig -o /boot/grub/grub.cfg
# mount -t sysfs /sys sys/
+
  # chroot . /bin/bash
+
  
And now:
+
Make sure that your Btrfs root is correctly added to the kernel commandline in {{ic|/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.
  
  # grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --boot-directory=/boot --recheck /dev/sda
+
  root=UUID=fd88d586-bb4c-4fc7-81a6-f675e2829581
  
Don't forget to update {{ic|/boot/grub/grub.cfg}}:
+
{{Warning|If you've set the default subvolume you '''MUST NOT''' add {{ic|subvol&#61;__active}} to your {{ic|rootflags}}.}}
  
# grub-mkconfig -o /boot/grub/grub.cfg
+
{{Note|Having boot on a different partition in not supported with {{AUR|mkinitcpio-btrfs}} >&#61; 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 {{ic|__active}} subvolume. Btrfs will automatically mount subvolume included in the currently mounted one.}}
  
You should now be able to reboot into GRUB, provided there were no problems encountered doing the steps above.
+
=== Syslinux EFI ===
  
=== Syslinux ===
+
To boot from Btrfs using syslinux EFI, you need to setup up a dedicated EFI partition in {{ic|/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]].
  
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:
+
{{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. {{AUR|mkinitcpio-btrfs}} will then mount your Btrfs root and reload the kernel from your Btrfs {{ic|/boot}} directory.}}
  
# syslinux-install_update -iam
+
In {{ic|/boot/efi/EFI/syslinux/syslinux.cfg}} make sure your Btrfs root is correctly added to the {{ic|APPEND}} line.
  
Then edit the {{ic|syslinux.cfg}}:
+
APPEND root=UUID=978e3e81-8048-4ae1-8a06-aa727458e8ff rw
  
Sample config:
+
{{Warning|If you've set the default subvolume you '''MUST NOT''' add {{ic|subvol&#61;__active}} to your {{ic|APPEND}} line.}}
  
{{hc|/boot/syslinux/syslinux.cfg|2=
+
== Usage Hints ==
PROMPT 0
+
TIMEOUT 0
+
DEFAULT arch
+
  
LABEL arch
+
To create a snapshot of your root filesystem execute:
        LINUX ../vmlinuz-linux
+
        APPEND root=/dev/disk/by-label/btrfs-root rootflags=subvol=__active ro
+
        INITRD ../initramfs-linux.img}}
+
  
If you '''ARE''' using the mkinitcpio hook, remove {{ic|1=rootflags=subvol=__active}} from the APPEND line.
+
# cd /var/lib/btrfs
 +
# sudo btrfs subvolume snapshot __active __snapshot/[snapshot name]
  
== Final configuration ==
+
Use {{ic|btrfs scrub}} for periodic online filesystem checks:
  
Almost done... be sure to edit {{ic|/mnt/etc/rc.conf}}, set the root password, and similar. Good luck on reboot!
+
# sudo btrfs scrub start /
 
+
  # sudo btrfs scrub status /
  # reboot
+
  
 
== Known issues ==
 
== Known issues ==
  
=== Rollback support ===
+
If you use a multi device ([[RAID]]) setup, make sure you rebalance after system upgrades, to prevent kernel panic on device failure:
 
+
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 {{AUR|mkinitcpio-btrfs}} 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 {{ic|ls}} may take seconds)
+
  
  # btrfs filesystem defrag /
+
  # sudo btrfs balance /

Revision as of 23:58, 24 October 2013

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 help replacing me
Installing on btrfs root Outlines a process for installing (or converting) Arch Linux to a btrfs root drive with syslinux or GRUB2.
Overview
Template:Boot process overview
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-btrfsAUR. 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-btrfsAUR >= 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-btrfsAUR. 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-btrfsAUR 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-btrfsAUR, 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-btrfsAUR 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-btrfsAUR 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-btrfsAUR >= 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-btrfsAUR 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 /