User:Fearedbliss/Installing Gentoo Linux On ZFS

Install Gentoo Linux on OpenZFS
Author: Jonathan Vasquez (fearedbliss) Contact: jon@xyinn.org

Preface
This guide will show you how to install Gentoo Linux on AMD64 with:

* UEFI-GPT (EFI System Partition) - This will be on a FAT32 unencrypted partition as per UEFI Spec. * /, /home, and /boot on ZFS * swap on regular partition * OpenZFS 0.8.3 * GRUB 2.04 (Bootloader) * systemd * Gentoo Stable (amd64)

Notes on other stuff you can do in the ZFS install can be found here.

Required Tools
Download my modified System Rescue CD that includes ZFS from one of the mirrors on the front page.

Linux
We will be creating a UEFI Bootable USB since this guide will be showing you how to install Gentoo Linux on ZFS with UEFI Enabled.

For the following commands, we will assume that your USB is /dev/sdg.

Create the FAT32 Filesystem on the USB
We will now create the FAT32 filesystem on the USB. This needs to be FAT32 since this is the filesystem used in the UEFI Specification. The label we will use for this partition will be in the following format SYSRCDXYZ, where XYZ is the version number of the System Rescue CD you downloaded.

For example, if you are using System Rescue CD 6.0.7, the label will be SYSRCD607.

Copy files over from ISO to USB
And that's it! You now have a Bootable UEFI USB.

Windows
You can download "Rufus" and select the ISO by clicking the little image next to the "Create a bootable disk using <>". After that, you can use the default settings and press "Start".

Download Rufus

Assumptions

 * Only installing Gentoo on one drive called /dev/sda (or /dev/nvme0n1, etc)
 * My modified System Rescue CD + ZFS iso is being used.
 * bliss-initramfs is being used as your initramfs.
 * bliss-kernel is being used as your kernel.

You are free to substitute any of the above for whatever you want if you know what you are doing (alternate kernels, initramfs generators, partition layouts (RAIDZ2?), etc). However, support will only be provided from me when the above configuration is used. Also, this guide is the way I install Gentoo, not exactly the way the handbook has it.

Confirm that you booted in UEFI Mode
After you booted into the Live CD, make sure that you booted into UEFI mode by typing the following:

If the above directory is empty or doesn't exist, you are not in UEFI mode. Reboot and boot into UEFI mode.

Partition
We will now partition the drive and aim to create the following layout:

/dev/sda1  | 512 MiB       |   EFI System Partition                | /boot/efi /dev/sda2  | 1024 MiB      |   Boot Partition (No Feature Flags)   | /boot /dev/sda3  | 2048 MiB      |   swap                                | swap /dev/sda4  | Rest of Disk  |   ZFS                                 | /, /home, ...

Open up your drive in GNU parted and tell it to use optimal alignment:

Create GPT partition layout
This will delete all partitions and create a new GPT table.

Final View
Exit the application

Create your zpool
Create your zpool which will contain your drives and datasets:

Create your zfs datasets
We will keep it simple and just create a few datasets for /, and /home. ZFS is extremely flexible and you can easily add or remove datasets in the future.

Create your boot pool
It is safer for us to create a separate zpool that has all feature flags disabled. This is because even though grub currently supports the latest feature flags for the 0.6.5 release of ZFS, new feature flags added to ZFS without proper bootloader support can make your system unbootable. Since GRUB 2 has solid support for a zpool with no feature flags, we will create a separate featureless boot pool. However, our main system will still have all features enabled.

Verify everything looks good
You can verify that all of these things worked by running the following:

Now we are ready to install Gentoo!

Set your date and time
Let's say it's August 24, 2014 @ 2:48 PM (will be 14:48 in 24 hour time), we would do the following:

Preparing to chroot
First let's mount our efi boot partition in our chroot directory:

and now download the systemd amd64 image here and extract it:

Edit fstab
Everything is on zfs so we don't need anything in here except for the boot and swap zvol entries. My fstab looks as follows:

Modify make.conf
Let's modify our /etc/portage/make.conf so we can start installing stuff with a good base (Change it to what you need):

Get the portage tree
Copy the default example portage config

Add 'bliss-overlay'
The 'bliss-overlay' repository contains some tools we need for a successful installation. We will be installing 'bliss-initramfs' which will allow your system to boot from your ZFS installation, and you will also have the option to install 'bliss-kernel-bin' which is a pre-compiled vanilla kernel (directly from kernel.org sources and no additional patches) that is ready to go and compatible with ZFS.

Open repos.conf and add bliss-overlay

Compile git

Sync once more to get bliss-overlay

Using the 'bliss-kernel' configuration
If you don't want to use the pre-compiled binaries for 'bliss-kernel', you can use the 'bliss-kernel' kernel configurations as a base for your kernel. The configuration is ready to go for general desktop, laptop, and server use, and it is also configured to work with ZFS. The 'bliss-kernel' configuration is simply a slightly tweaked Fedora config.

You can download the 'bliss-kernel' configurations here.

Using the pre-compiled 'bliss-kernel' binaries
Install the kernel

Install required applications
Unmask latest ZFS versions

Enable ZFS support in GRUB

Now install the apps:

Installing the bootloader onto your drive
We will need to install the bootloader onto the drive. Before we do that however, let's see if GRUB can detect our /boot and /boot/efi filesystem types:

This should say 'zfs'. If it doesn't, then something is wrong and your system will not boot!

This should say 'fat'. If it doesn't, then something is wrong and your system will not boot!

Before we install the bootloader, we will need to have read/write access to the efi nvram variables. Let's remount our efivars now:

Now run the following to install the bootloader to the drive:

The above command will install the grub bootloader files into /boot and the efi files into /boot/efi. It should return a "Installation finished. No error reported." message. If it doesn't, then something is wrong and your system will not boot!

Make the GRUB 2 configuration file
You can use the following configuration file as a basis for your system:

Generating new zpool.cache file before/after reboot
ZFS is very sensitive about the data that is contained in the zpool.cache file and at this point, when we reboot, the information in it might not be completely accurate. To ensure we have a good cache file, we have instructed bliss-initramfs in the bootloader config above, to ignore the current cachefile on the system, and make a new one that is up-to-date. We only need to do this once.

Remove zpool.cache refresh flag from bootloader configuration
Open up your grub.cfg and remove the 'refresh' flag from the kernel line.

Take a snapshot of your new system
Since we now have a working system, we will snapshot it in case we ever want to go back or recover files:

You can view the contents of these snapshots by checking their respective and hidden .zfs directories:

Bliss ZFS Scripts
The following scripts allow you to automatically:


 * Take snapshots of your pool
 * Replicate the pool to another pool (Full and Incremental Backups)
 * Clean the old snapshots on your pools.

You can download, customize, and install the scripts into your /usr/local/sbin directory. Github.

And that's it. Enjoy!