Difference between revisions of "Mkinitcpio-btrfs"

From ArchWiki
Jump to: navigation, search
(Syslinux)
(simplification and beautification of wikilinks, fixing whitespace, capitalization and section fragments (https://github.com/lahwaacz/wiki-scripts/blob/master/link-checker.py (interactive)))
 
(41 intermediate revisions by 20 users not shown)
Line 1: Line 1:
[[Category:Getting and installing Arch]]
+
[[Category:Boot process]]
{{Article summary start}}
+
{{Related articles start}}
{{Article summary text|Installing on btrfs root Outlines a process for installing (or converting) Arch Linux to a btrfs root drive with syslinux or GRUB2.}}
+
{{Related|Installation guide}}
{{Article summary heading|Overview}}
+
{{Related|Beginners' guide}}
{{Article summary text|{{Boot process overview}}}}
+
{{Related|mkinitcpio}}
{{Article summary heading|Resources}}
+
{{Related|Btrfs}}
{{Article summary text|[[Wikipedia:Btrfs|Btrfs — Wikipedia]]}}
+
{{Related|GRUB}}
{{Article summary link|FAQ — Btrfs Wiki|https://btrfs.wiki.kernel.org/articles/f/a/q/FAQ_1fe9.html#Is_btrfs_stable.3F}}
+
{{Related|Syslinux}}
{{Article summary link|GNU GRUB — GNU Project|https://gnu.org/s/grub/}}
+
{{Related articles end}}
{{Article summary link|Syslinux Website|http://www.syslinux.org/wiki/index.php/The_Syslinux_Project}}
+
{{Poor writing|Style on this page is not coherent with [[Help:Style]].|section=Things to do (accuracy & style)}}
{{Article summary text|[[Wikipedia:GUID Partition Table|GUID Partition Table — Wikipedia]]}}
+
{{Accuracy|This page needs extensive editing or an outright re-write. Caution may be warranted until this is completed. See [[Btrfs]] and the discussion for further information.|section=Things to do (accuracy & style)}}
{{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.
+
Some of Btrfs's neat features like non-volatile rollback or automatic mounting of degraded Btrfs multi-device ([[RAID]]) volumes need a special package from the [[Arch User Repository]] called {{AUR|mkinitcpio-btrfs}}. The package integrates some helpers in the boot process, to handle these features correctly.
  
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.
+
{{Note|
 +
* This article assumes that you are creating a fresh install.
 +
* 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.}}
  
{{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.}}
+
== Setup ==
  
== btrfs-progs ==
+
{{Warning|
 +
* Be aware of the differences between ''partitions'' and ''sub-volumes''.
 +
* Having a separate ''/boot'' '''partition''' is not supported by {{AUR|mkinitcpio-btrfs}}
 +
* kexec is used to reload the kernel from the root partition to make sure it is rolled back also.
 +
* ''/boot'' '''can''' be on a sub-volume within your {{ic|__active}} sub-volume.}}
  
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.
 
  
== mkinitcpio-btrfs ==
+
Create a ''snapshot'' of the current root directory. Creating a snapshot automatically creates a new sub-volume. Name this snapshot {{ic|__active}}. Later on, this will serve as the system's new root directory.
  
To get rollback features on your btrfs root device, you will need to install the {{AUR|mkinitcpio-btrfs}} package from the [[Arch User Repository]].
+
# cd /mnt
 +
# btrfs subvolume snapshot . __active
  
For reference, here are the internal variables used by {{AUR|mkinitcpio-btrfs}}:
+
To use the rollback features of Btrfs, create a {{ic|__snapshot}} directory for snapshot storage.
 
+
${BTRFS_HAS_ROLLBACK:=true}
+
${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.}}
+
 
+
== 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:
+
 
+
# rsync -aAXv --exclude={dev,sys,proc,mnt,tmp,media} / <dest>/`date +%Y-%m-%d-%T`/
+
 
+
To restore from an rsync backup, just reverse the paths. It is also possible to use tar:
+
 
+
{{bc|1=# tar -cvpPJf $BACKUPDIR/$FILENAME --exclude="/proc/*" --exclude="/sys/*" \
+
--exclude="/mnt/*" --exclude="/media/*" --exclude="/dev/*" --exclude="/tmp/*" /}}
+
 
+
and to restore from a tar backup:
+
 
+
# tar -xvpJf <backup_file> -C <root>
+
 
+
== Boot into a live image ==
+
 
+
It is recommended that you boot and install from the latest [http://www.archlinux.org/download/ 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 {{Pkg|btrfs-progs}} is installed and functioning correctly:
+
 
+
# btrfs --help
+
 
+
{{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].}}
+
 
+
{{Note|It is possible to allow btrfs to use the entire hard drive without using a partitioning scheme, but that is not recommended. [https://wiki.archlinux.org/index.php/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|[[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 ===
+
 
+
To get started partitioning, we must [[pacman|install]] the {{Pkg|gptfdisk}} package from the [[Official Repositories]]:
+
 
+
# pacman -S gptfdisk
+
 
+
[[GRUB2]] requires a +2M boot partition at the front of the drive [https://wiki.archlinux.org/index.php/GRUB2#GPT_specific_instructions]. You can create that with gdisk:
+
 
+
# gdisk /dev/sda
+
 
+
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
+
then use {{ic|p}} to verify the output:
+
 
+
{{bc|
+
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 ===
+
 
+
With the drive partitioned and ready for a filesystem, make sure {{Pkg|btrfs-progs}} is installed and create the filesystem on the root partition:
+
 
+
# 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.}}
+
 
+
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:
+
  
 +
# 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 sub-volume and folder names are chosen for compatibility with {{AUR|mkinitcpio-btrfs}}.  
 +
* Different names can be used if later specified 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 sub-volumes for important directories. This would additionally enable the ability to monitor and adjust the size allocations for each sub-volume using {{ic|btrfs quota}}.
  
# mkdir boot
+
See [[Btrfs#Subvolumes]]
  
{{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.}}
+
{{Note|For mkinitcpio-btrfs compatibility, set the default sub-volume to {{ic|__active}}.}}
  
Next we will create the subvolumes. To see all the commands available to manage subvolumes with btrfs:
+
{{Warning|{{AUR|mkinitcpio-btrfs}} may not handle sub-volumes correctly. See [https://github.com/xtfxme/mkinitcpio-btrfs/issues/6 here].}}
  
# 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}}:
+
Next, mount the root sub-volume. See [[Btrfs#Mount options]].
  
{{Note|{{ic|__active}} is chosen for integration with current {{AUR|mkinitcpio-btrfs}}. See the variable reference above, or the source mkinitcpio-btrfs package.}}
+
{{Note|If you did not set the default subvolume you need to add an additional {{ic|subvol&#61;__active}} mount option.}}
  
# btrfs subvolume create __active && cd __active
+
== Configure the system ==
  
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:
+
Create a place where you mount the Btrfs root subvolume to create snapshots later.
  
  # btrfs subvolume create home
+
  # mkdir /var/lib/btrfs
# btrfs subvolume create var
+
{{Note|This should probably be {{ic|/mnt/var/lib/btrfs}} as we haven't chrooted yet.}}
# btrfs subvolume create usr
+
  
To see your handy work:
+
{{Tip|bind an empty folder over the {{ic|/var/lib/btrfs/__active}} folder to prevent apps such as 'find' from complaining of any loops. {{ic|/var/lib/btrfs/empty  /var/lib/btrfs/__active  none  bind  0  0}}}}
  
{{hc|# btrfs subvolume list -p .|
+
== Installation ==
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
+
}}
+
  
Fix the permissions:
+
Install {{AUR|mkinitcpio-btrfs}} from the [[Arch User Repository]].
  
chmod 755 ../\__active var usr home
+
Modify {{ic|/etc/default/btrfs_advanced}} as needed and add {{ic|btrfs_advanced}} to the {{ic|HOOKS}} section in {{ic|/etc/mkinitcpio.conf}}.
  
Now that the subvolumes are created and we have a layout, lets mount the root subvolume directly:
+
Re-create the initial ramdisk environment. See [[Mkinitcpio#Image creation and activation]]
  
# mkdir /mnt/btrfs-active
+
== Install and configure a bootloader ==
# 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.}}
+
See [[Btrfs#Installation]]
 
+
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 {{ic|__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 ==
+
 
+
{{Accuracy}}
+
 
+
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 {{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 ===
+
 
+
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/btrfs-active/etc/fstab
+
 
+
==== GRUB2 ====
+
 
+
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
+
 
+
{{Note|If you are not using an SSD drive, remove {{ic|discard,ssd}} from the mount options.}}
+
 
+
==== Syslinux ====
+
 
+
{{Tip|Locations chosen for integration with upcoming release of mkinitcpio-btrfs}}
+
 
+
Add everything to {{ic|/mnt/btrfs-active/etc/fstab}} ... {{ic|(btrfs-root)/boot}} will be --bind mounted so kernel upgrades work:
+
 
+
{{hc|/etc/fstab|2=
+
/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.
+
 
+
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.
+
 
+
==== mkinitcpio-btrfs ====
+
 
+
Download the mkinitcpio-btrfs tarball:
+
 
+
# wget -O /mnt/btrfs-active/root/mkinitcpio-btrfs.tar.gz http://aur.archlinux.org/packages/mk/mkinitcpio-btrfs/mkinitcpio-btrfs.tar.gz
+
 
+
Add {{ic|btrfs_advanced}} to the {{ic|HOOKS}} section of {{ic|/mnt/btrfs-active/etc/mkinitcpio.conf}}:
+
 
+
{{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
+
 
+
== Installing the 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.
+
  
 
=== GRUB ===
 
=== GRUB ===
  
See [[GRUB]] for advanced instructions. Once you have GRUB configured, and you chrooted into your install directory, install the boot loader.
+
{{Tip|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:
+
 
+
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:
+
 
+
# cp /etc/resolv.conf etc/
+
# mount -o bind /dev dev/
+
# mount -t proc /proc proc/
+
# mount -t sysfs /sys sys/
+
# chroot . /bin/bash
+
 
+
And now:
+
 
+
# grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --boot-directory=/boot --recheck /dev/sda
+
 
+
Don't forget to update {{ic|/boot/grub/grub.cfg}}:
+
 
+
# grub-mkconfig -o /boot/grub/grub.cfg
+
 
+
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:
+
 
+
# syslinux-install_update -iam
+
 
+
Then edit the {{ic|syslinux.cfg}}:
+
 
+
Sample config:
+
 
+
{{hc|/boot/syslinux/syslinux.cfg|2=
+
PROMPT 0
+
TIMEOUT 0
+
DEFAULT arch
+
 
+
LABEL arch
+
        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.
+
 
+
== Final configuration ==
+
  
Almost done... be sure to edit {{ic|/mnt/etc/rc.conf}}, set the root password, and similar. Good luck on reboot!
+
{{Tip|To have your multi-device Btrfs boot if your first device has failed, add the bootloader to the second device too.}}
  
# reboot
+
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.
  
== Known issues ==
+
root=UUID=fd88d586-bb4c-4fc7-81a6-f675e2829581
  
=== Rollback support ===
+
{{Warning|If you've set the default subvolume you '''MUST NOT''' add {{ic|subvol&#61;__active}} to your {{ic|rootflags}}.}}
  
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.
+
{{Note|Having boot on a different partition in not supported with {{AUR|mkinitcpio-btrfs}} >&#61; 0.4.}}
  
=== Syslinux ===
+
=== Syslinux EFI ===
  
* Syslinux operates successfully through times, but sometimes fails.
+
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]].
  
* 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.
+
{{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.}}
  
=== Slow meta-data after installation ===
+
In {{ic|/boot/efi/EFI/syslinux/syslinux.cfg}} make sure your Btrfs root is correctly added to the {{ic|APPEND}} line.
  
Do a defragmentation of / after the installation is done to fix the slow metadata issue. (a simple {{ic|ls}} may take seconds)
+
APPEND root=UUID=978e3e81-8048-4ae1-8a06-aa727458e8ff rw
  
# btrfs filesystem defrag /
+
{{Warning|If you've set the default subvolume you '''MUST NOT''' add {{ic|subvol&#61;__active}} to your {{ic|APPEND}} line.}}

Latest revision as of 12:31, 28 March 2016

Tango-edit-clear.pngThis article or section needs language, wiki syntax or style improvements.Tango-edit-clear.png

Reason: Style on this page is not coherent with Help:Style. (Discuss in Talk:Mkinitcpio-btrfs#Things to do (accuracy & style))

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: This page needs extensive editing or an outright re-write. Caution may be warranted until this is completed. See Btrfs and the discussion for further information. (Discuss in Talk:Mkinitcpio-btrfs#Things to do (accuracy & style))

Some of Btrfs's neat features like non-volatile rollback or automatic mounting of degraded Btrfs multi-device (RAID) volumes need a special package from the Arch User Repository called mkinitcpio-btrfsAUR. The package integrates some helpers in the boot process, to handle these features correctly.

Note:
  • This article assumes that you are creating a fresh install.
  • 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.

Setup

Warning:
  • Be aware of the differences between partitions and sub-volumes.
  • Having a separate /boot partition is not supported by mkinitcpio-btrfsAUR
  • kexec is used to reload the kernel from the root partition to make sure it is rolled back also.
  • /boot can be on a sub-volume within your __active sub-volume.


Create a snapshot of the current root directory. Creating a snapshot automatically creates a new sub-volume. Name this snapshot __active. Later on, this will serve as the system's new root directory.

# cd /mnt
# btrfs subvolume snapshot . __active

To use the rollback features of Btrfs, create a __snapshot directory for snapshot storage.

# cd /mnt
# mkdir __snapshot
Note:
  • The sub-volume and folder names are chosen for compatibility with mkinitcpio-btrfsAUR.
  • Different names can be used if later specified in /etc/default/btrfs_advanced later.

You can create separate sub-volumes for important directories. This would additionally enable the ability to monitor and adjust the size allocations for each sub-volume using btrfs quota.

See Btrfs#Subvolumes

Note: For mkinitcpio-btrfs compatibility, set the default sub-volume to __active.
Warning: mkinitcpio-btrfsAUR may not handle sub-volumes correctly. See here.


Next, mount the root sub-volume. See Btrfs#Mount options.

Note: If you did not set the default subvolume you need to add an additional subvol=__active mount option.

Configure the system

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

# mkdir /var/lib/btrfs
Note: This should probably be /mnt/var/lib/btrfs as we haven't chrooted yet.
Tip: 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

Installation

Install mkinitcpio-btrfsAUR from the Arch User Repository.

Modify /etc/default/btrfs_advanced as needed and add btrfs_advanced to the HOOKS section in /etc/mkinitcpio.conf.

Re-create the initial ramdisk environment. See Mkinitcpio#Image creation and activation

Install and configure a bootloader

See Btrfs#Installation

GRUB

Tip: 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.
Tip: To have your multi-device Btrfs boot if your first device has failed, add the bootloader to the second device too.

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.

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.