Gentoo ZFS Install
==================

ZFS on root
-----------

ref: `ZFS/rootfs <https://wiki.gentoo.org/wiki/ZFS/rootfs#Live_Media>`_

Partitions
~~~~~~~~~~
Layout


Follow the Handbook 
----------------------

- Section on Preparing the disks returning **at the creating file** systems section.
- This guide will be using the example below however it should be simple enough to adapt this to the user's needs.

.. list-table:: Disk Partitioning
   :header-rows: 1
   :widths: 20 20 30 30

   * - Device
     - Size
     - Partition
     - Mount Point
   * - ``/dev/sda1``
     - 1024 MiB
     - EFI System Partition
     - ``/boot/efi``
   * - ``/dev/sda2``
     - 2048 MiB
     - swap
     - swap
   * - ``/dev/sda3``
     - Rest of Disk
     - ZFS Partition
     - ``/, /boot, /home,`` ...

The document used ``/efi`` as the mount point, but other docs use ``/boot/efi``.

Boot
~~~~~~~~~~

.. code-block:: bash

    mkfs.vfat -F 32 /dev/sda1


Swap
~~~~~~~~~~

.. code-block:: bash

   mkswap /dev/sda2
   swapon /dev/sda2

ZFS Setup
~~~~~~~~~~~

Generate host ID

Randomly generate host ID into /etc/hostid allowing output overwrite.

.. code-block:: bash

    zgenhostid -f

Alternatively, set a specific host ID, 0x00bab10c in this example.

.. code-block:: bash

    zgenhostid -f 0x00bab10c

Create a ZFS pool

Load ZFS kernel module and create a ZFS pool tank on /dev/sda3.

.. code-block:: bash

    modprobe zfs

    zpool create -f \
        -o ashift=12 \
        -o autotrim=on \
        -o compatibility=openzfs-2.1-linux \
        -O acltype=posixacl \
        -O xattr=sa \
        -O relatime=on \
        -O compression=lz4 \
        -m none tank /dev/sda3

.. note::

    The option ``-o compatibility=openzfs-2.1-linux`` makes sure that GRUB works. If you are using ZFSBootMenu, you can skip that option.

Create ZFS file systems
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

    zfs create -o mountpoint=none tank/os
    zfs create -o mountpoint=/ -o canmount=noauto tank/os/gentoo
    zfs create -o mountpoint=/home tank/home

    zpool set bootfs=tank/os/gentoo tank
    zpool export tank
    zpool import -N -R /mnt/gentoo tank
    zfs mount tank/os/gentoo
    zfs mount tank/home
    mount -t zfs

Here is an example of the command output in case of successful mounting of file systems.
::

    tank/os/gentoo /mnt/gentoo type zfs (rw,relatime,xattr,posixacl)
    tank/home on /mnt/gentoo/home type zfs (rw,relatime,xattr,posixacl)

Update device symbolic links: 

.. code-block:: bash

    udevadm trigger

Return to the Handbook 
------------------------

- EFI_system_partition_filesyste and return **just before entering chroot** command. 

.. code-block:: bash

    cp /etc/hostid /mnt/gentoo/etc

Return to the Handbook 
-----------------------

- Installing Gentoo base system and return here at **Kernel configuration** and compilation. 

Kernel
~~~~~~~~~~~~~~

Edit ``/etc/portage/make.conf``

.. code-block:: bash

    vim /etc/portage/make.conf
    # Add the following line for distrubution kernel support
    USE="dist-kernel"

.. code-block:: bash

    emerge -av sys-kernel/gentoo-kernel

.. note::

    if you prefer using the pre-compiled binary,
    emerge -av sys-kernel/gentoo-kernel-bin


ZFS userland utilities and kernel module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The sys-fs/zfs and sys-fs/zfs-kmod packages are necessary to allow your system to interact with and manage your ZFS pools.

.. code-block:: bash

    emerge -av sys-fs/zfs sys-fs/zfs-kmod


Initramfs
~~~~~~~~~~~~~~~~~~~~~

Create a directory for Dracut configuration files if it does not exist.

.. code-block:: bash

    mkdir -p /etc/dracut.conf.d

Then, create a file zol.conf with the following content in this directory:

.. code-block:: bash

    vim /etc/dracut.conf.d/zol.conf


FILE /etc/dracut.conf.d/zol.confDracut configuration for ZFS
::

    nofsck="yes"
    add_dracutmodules+=" zfs "


Build the initramfs for the distribution kernel

.. code-block:: bash

    emerge --config sys-kernel/gentoo-kernel

.. note::

    Or, if the binary version was installed,
    emerge --config sys-kernel/gentoo-kernel-bin

Return to the Handbook
-----------------------

- Configuring the system and return here at **Configuring the bootloader** for anything other than ``sys-boot/grub``. 

Bootloader
~~~~~~~~~~~~~~

.. code-block:: bash

    zfs set org.zfsbootmenu:commandline="quiet loglevel=4" tank/os

.. warning::

    Therefore, the -systemd USE flag must be added to sys-kernel/installkernel to prevent that from happening.

**If** the ESP was not mounted previously, it is necessary to do it now:

.. code-block:: bash

    mkdir -p /boot/efi
    mount /dev/sda1 /boot/efi

ZFSBootMenu 
~~~~~~~~~~~~~~~~~~~~~~~~

Installing ZFSBootMenu (prebuilt)

Create a directory for the bootloader and download the EFI binary into it. 

.. code-block:: bash

    mkdir -p /boot/efi/EFI/BOOT
    curl -L https://get.zfsbootmenu.org/efi -o /boot/efi/EFI/BOOT/BOOTX64.EFI

    emerge -av sys-boot/efibootmgr
    efibootmgr -c -d /dev/sda -p 1 -L "ZFSBootMenu" -l \\BOOT\\EFI\\BOOT\\BOOTX64.EFI

Rebooting the system
----------------------------

Exit the chrooted environment and unmount all mounted partitions, do not forget to export the pool. After that, the system can be rebooted.

.. code-block:: bash

    exit
    cd
    umount -l /mnt/gentoo/dev{/shm,/pts,}
    umount -n -R /mnt/gentoo
    zpool export tank
    reboot