The Funtoo Linux project has transitioned to "Hobby Mode" and this wiki is now read-only.
Difference between revisions of "ZFS as Root Filesystem"
| (89 intermediate revisions by 9 users not shown) | |||
| Line 1: | Line 1: | ||
{{warning|This page is unofficial. ZFS as root filesystem is not supported under Funtoo Linux, mainly because it has limited benefit. ZFS is still supported but boot on a non-ZFS filesystem first. See [[ZFS]].}} | |||
== Introduction == | == Introduction == | ||
This wiki will show you how to install Funtoo on ZFS (rootfs). | This wiki article will show you how to install Funtoo on ZFS (rootfs). | ||
== Prerequisites == | == Prerequisites == | ||
{{fancyimportant|''ZFS designed for 64-bit systems. We only | {{fancyimportant|''ZFS is designed for 64-bit systems. We only recommend and support 64-bit platforms and installations!''}} | ||
ZFS | {{fancywarning|''ZFS v07.5 (latest in ports as of 18 Jan 2018) is compatible with kernel versions 2.6.32 - 4.14''}} | ||
{{fancywarning|''The guide is under rewrite''}} | |||
It is recommended to give the entire disk to ZFS. As such, this guide will only show how to install ZFS on the whole disk, using legacy boot. Installing on UEFI requires a separate partition for /boot, formatted as FAT32, and is out of the scope of this guide, even though installation on UEFI is certainly possible. Also, this guide will not cover anything related to encryption (native encryption is available: https://github.com/zfsonlinux/zfs/commit/b52563034230b35f0562b6f40ad1a00f02bd9a05). | |||
=== Downloading the ISO (With ZFS) === | === Downloading the ISO (With ZFS) === | ||
In order to install Funtoo on ZFS, you will need an environment such as live media | In order to install Funtoo on ZFS, you will need an environment, such as live media, that provides the ZFS tools. This guide will utilize the Ubuntu Desktop 16.04 (live) DVD for amd64. | ||
* Download from '''[ | * Download from '''[https://build.funtoo.org/distfiles/ubuntu-17.10.1-desktop-amd64.iso]''' | ||
== Creating a bootable USB from ISO (From a Linux Environment) == | == Creating a bootable USB from ISO (From a Linux Environment) == | ||
After you download the iso, you can do the following steps to create a bootable USB: | After you download the iso, you can do the following steps to create a bootable USB: | ||
{{note|The size of the iso is approximately 1. | {{note|The size of the iso is approximately 1.5 GB.}} | ||
Insert your blank USB media into a USB port. | Insert your blank USB media into a USB port. Then, inspect the kernel ring buffer with {{c|dmesg}} to identify the device name of your USB storage. | ||
{{console|title=dmesg|body= | {{console|title=dmesg|body= | ||
[ +5.533491] usb 6-2: new SuperSpeed USB device number 4 using xhci_hcd | [ +5.533491] usb 6-2: new SuperSpeed USB device number 4 using xhci_hcd | ||
| Line 32: | Line 37: | ||
[ +0.359532] sd 15:0:0:0: [sdg] Attached SCSI removable disk | [ +0.359532] sd 15:0:0:0: [sdg] Attached SCSI removable disk | ||
}} | }} | ||
In this example | In this example, {{c|[sdg]}} indicates that the device is {{c|/dev/sdg}}. | ||
A quick and easy way to create a bootable USB is to write the ISO data to the USB device using {{c|dd}}. | A quick and easy way to create a bootable USB is to write the ISO data to the USB device using {{c|dd}}. | ||
| Line 39: | Line 44: | ||
}} | }} | ||
Once this has completed remove and use this USB to boot the target system that will receive Funtoo Linux. | Once this has completed, remove and use this USB to boot the target system that will receive Funtoo Linux. | ||
== Booting the ISO == | == Booting the ISO == | ||
Using legacy (BIOS) boot mode, boot the | Using legacy (BIOS) boot mode, boot the ISO and allow Ubuntu to load the graphical environment. You will be presented with a "Welcome" dialog (titled ''Install (as superuser)''). Select the option "Try Ubuntu". | ||
Once the desktop has loaded open the search bar by left-clicking on the top-left icon ("Search your computer"). Pressing Alt+F1 should also open this search bar. Search for and open the Terminal application. | Once the desktop has loaded, open the search bar by left-clicking on the top-left icon ("Search your computer"). Pressing Alt+F1 should also open this search bar. Search for and open the Terminal application. | ||
In the terminal, issue the following commands to install and load the required ZFS module. | In the terminal, issue the following commands to install and load the required ZFS module. | ||
| Line 55: | Line 60: | ||
}} | }} | ||
Verify that the ZFS kernel module has loaded. | |||
{{console|body= | {{console|body= | ||
root@ubuntu:~# ##i## dmesg {{!}} grep ZFS | root@ubuntu:~# ##i## dmesg {{!}} grep ZFS | ||
| Line 62: | Line 67: | ||
== Drive Partitions == | == Drive Partitions == | ||
We are letting ZFS automatically partition the drive. This ideal for our example using a single disk and legacy (BIOS) boot. | We are letting ZFS automatically partition the drive. This is ideal for our example using a single disk and legacy (BIOS) boot. | ||
=== Creating of pool === | === Creating of pool === | ||
Create a ZFS Storage Pool using a single whole disk | Create a ZFS Storage Pool using a single whole disk. | ||
<console> | <console> | ||
root@ubuntu:~###i## zpool create -f -o ashift=12 -o cachefile=/tmp/zpool.cache -O normalization=formD -O atime=off -m none -R /mnt/funtoo rpool /dev/disk/by-id/foo | root@ubuntu:~###i## zpool create -d -o feature@async_destroy=enabled -o feature@empty_bpobj=enabled -o feature@lz4_compress=enabled -o feature@spacemap_histogram=enabled -o feature@enabled_txg=enabled -o feature@extensible_dataset=enabled -o feature@bookmarks=enabled -f -o ashift=12 -o cachefile=/tmp/zpool.cache -O normalization=formD -O atime=off -O xattr=sa -O compression=lz4 -m none -R /mnt/funtoo rpool /dev/disk/by-id/foo | ||
</console> | </console> | ||
The options used here are | The options used here are | ||
| Line 73: | Line 78: | ||
{{2ColHead|option|description}} | {{2ColHead|option|description}} | ||
{{2Col|{{c|create}}|Use {{c|zpool}} to create a ZFS Storage Pool.}} | {{2Col|{{c|create}}|Use {{c|zpool}} to create a ZFS Storage Pool.}} | ||
{{2Col|{{c|-d}}|Required. Disables enabling all availabe zfs features. This is needed as the GRUB bootloader currently can't handle all advanced zfs features, not specifying this flag on pool creation (or running 'zpool upgrade' on the pool at a later point in time) will make the pool incompatible with GRUB.}} | |||
{{2Col|{{c|(multiple) -o feature@<name>{{=}}enabled}}|Explicitely enable all features currently supported by GRUB. See 'man zpool-features' for details on their effects.}} | |||
{{2Col|{{c|-f}}|Force the use of the selected disk.}} | {{2Col|{{c|-f}}|Force the use of the selected disk.}} | ||
{{2Col|{{c|-o ashift{{=}}12}}|Alignment of the pool to underlying | {{2Col|{{c|-o ashift{{=}}12}}|Alignment of the pool to underlying hard drive sectors. The recommended value is 12, which corresponds to 2^12 Bytes or 4 KiB. This value is typical for present-day HDD's. Can only be set once at pool creation.}} | ||
{{2Col|{{c|-o cachefile{{=}}/tmp/zpool.cache}}|Create a pool configuration cache and place it in {{f|/tmp}}. This will be required for our Funtoo install.}} | {{2Col|{{c|-o cachefile{{=}}/tmp/zpool.cache}}|Create a pool configuration cache and place it in {{f|/tmp}}. This will be required for our Funtoo install.}} | ||
{{2Col|{{c|-O normalization{{=}}formD}}|Recommended. Set the default Unicode (UTF-8) normalization for future filesystems (created within this pool) to 'formD'.}} | {{2Col|{{c|-O normalization{{=}}formD}}|Recommended. Set the default Unicode (UTF-8) normalization for future filesystems (created within this pool) to 'formD'.}} | ||
{{2Col|{{c|-O atime{{=}}off}}| | {{2Col|{{c|-O atime{{=}}off}}|Recommended. As a default preference, set future filesystems (created within this pool) to not update file access time. Useful if we want to reduce writes to disk (e.g., Solid State Drives). Can cause problems for mailers and other software that rely on file access-time data.}} | ||
{{2Col|{{c|-O xattr{{=}}sa}}|Recommended. As a default preference, set future filesystems (created within this pool) to store extended file attributes in a more efficient manner.}} | |||
{{2Col|{{c|-O compression{{=}}lz4}}|Recommended. As a default preference, set future filesystems (created within this pool) to be compressed using the lz4 algorithm. Useful in general as the runtime cost for compression is neglible on these days while on-disk space still costs money.}} | |||
{{2Col|{{c|-m none}}|Do not set mountpoint for this storage pool. (This guide will address this later).}} | {{2Col|{{c|-m none}}|Do not set mountpoint for this storage pool. (This guide will address this later).}} | ||
{{2Col|{{c|-R /mnt/funtoo}}|Alternate root directory. Essentially a temporary 'mount point' for our pool.}} | {{2Col|{{c|-R /mnt/funtoo}}|Alternate root directory. Essentially a temporary 'mount point' for our pool.}} | ||
{{2Col|{{c|rpool}}|The name of this ZFS Storage Pool. The pool name is irrelevant | {{2Col|{{c|rpool}}|The name of this ZFS Storage Pool. The pool name is irrelevant. {{c|rpool}} will be used throughout this guide.}} | ||
{{2Col|{{c|/dev/disk/by-id/foo}}|The path to the physical disk. e.g. /dev/disk/by-id/ata-Samsung_SSD_840_EVO_120GB_123456789ABCDEF. Known in 'ZFS-speak' as a 'VDEV'.}} | {{2Col|{{c|/dev/disk/by-id/foo}}|The path to the physical disk. e.g. /dev/disk/by-id/ata-Samsung_SSD_840_EVO_120GB_123456789ABCDEF. Known in 'ZFS-speak' as a 'VDEV'.}} | ||
{{TableEnd}} | {{TableEnd}} | ||
Please note that the options 'ashift' and 'cachefile' are preceded with a lowercase '-o', while 'normalization' and 'atime' are preceded with an uppercase '-O'. | Please note that the options 'ashift' and 'cachefile' are preceded with a lowercase '-o', while 'normalization' and 'atime' are preceded with an uppercase '-O'. | ||
Without additional options this will create our storage pool and enable all 'features' available under version 0.6.5.6. The pool will be automatically mounted at the (temporary) location {{f|/mnt/funtoo}}. | Without additional options, this will create our storage pool and enable all 'features' available under version 0.6.5.6. The pool will be automatically mounted at the (temporary) location {{f|/mnt/funtoo}}. | ||
To confirm the presence of our newly created pool | To confirm the presence of our newly created pool: | ||
{{console|body= | {{console|body= | ||
root@ubuntu:~###i## zpool status | root@ubuntu:~###i## zpool status | ||
| Line 103: | Line 112: | ||
=== Create ZFS Datasets === | === Create ZFS Datasets === | ||
Now we will create one or more ZFS datasets within our storage pool. These will contain Funtoo Linux. | Now, we will create one or more ZFS datasets within our storage pool. These will contain Funtoo Linux. | ||
==== Create the Root file system (Required) ==== | ==== Create the Root file system (Required) ==== | ||
<console> | <console> | ||
| Line 110: | Line 119: | ||
</console> | </console> | ||
==== Create optional Datasets==== | ==== Create optional Datasets==== | ||
The following optional datasets are provided as examples. It is up to the user to create their own datasets. | |||
===== Home===== | ===== Home===== | ||
<console> | <console> | ||
# ##i## zfs create -o mountpoint=/home rpool/HOME | # ##i## zfs create -o mountpoint=/home rpool/HOME | ||
</console> | </console> | ||
=====Build directory===== | =====Build directory===== | ||
<console> | <console> | ||
# ##i## zfs create -o mountpoint=none -o canmount=off rpool/FUNTOO | |||
# ##i## zfs create -o mountpoint=/var/tmp/portage -o compression=lz4 -o sync=disabled rpool/FUNTOO/build | # ##i## zfs create -o mountpoint=/var/tmp/portage -o compression=lz4 -o sync=disabled rpool/FUNTOO/build | ||
</console> | </console> | ||
=====Swap on ZFS===== | |||
With some careful tuning a swap partition can be created on a ZFS 'volume' [https://github.com/zfsonlinux/zfs/wiki/FAQ]. For a 2 GB swapfs: | |||
{{console|body= | |||
# ##i## zfs create -V 2G -b $(getconf PAGESIZE) -o logbias=throughput -o sync=always -o primarycache=metadata rpool/swap | |||
# ##i## mkswap /dev/zvol/rpool/swap | |||
# ##i## swapon /dev/zvol/rpool/swap | |||
}} | |||
Note that swap on ZFS has known stability issues. If the user has decided to use swap, please take following into account: | |||
Always use long <code>/dev/zvol</code> aliases in configuration files. Never use a short <code>/dev/zdX</code> device name. | |||
To confirm the presence of the filesystems that we have created | To confirm the presence of the filesystems that we have created: | ||
{{console|body= | {{console|body= | ||
root@ubuntu:~# ##i##zfs list -t all | root@ubuntu:~# ##i##zfs list -t all | ||
| Line 145: | Line 158: | ||
== Installing Funtoo == | == Installing Funtoo == | ||
Now that initial ZFS pool created | Now that the initial ZFS pool and datasets have been created, we can unpack the stage 3 tarball and proceed with basic system installation. This part does not differ much from a regular Funtoo Linux installation (https://www.funtoo.org/Install#Installing_the_Stage_3_tarball). We recommend using <code>funtoo-current</code> stages for ZFS. | ||
{{console|body= | {{console|body= | ||
# ##i## cd /mnt/funtoo | # ##i##cd /mnt/funtoo | ||
# ##i## wget | # ##i##wget https://build.funtoo.org/next/x86-64bit/generic_64/stage3-latest.tar.xz | ||
}} | }} | ||
Extract the contents with the following command. If the user is using an arch-optimized stage 3 tarball, substitute in the actual filename. | |||
Extract the contents with the following command | |||
{{console|body= | {{console|body= | ||
# ##i## tar xpf stage3-latest.tar.xz | # ##i##cd /mnt/funtoo | ||
# ##i##tar xpf stage3-latest.tar.xz | |||
}} | }} | ||
Now we need to create chroot environment | Now, we need to create a chroot environment: | ||
{{console|body= | {{console|body= | ||
| Line 167: | Line 180: | ||
}} | }} | ||
An important step is to copy the ZFS cache into the chroot. The ZFS cache was created when <code>rpool</code> was created with the <code>-o cachefile=/tmp/zpool.cache</code> flag. | |||
{{console|body= | {{console|body= | ||
# ##i##mkdir -p /mnt/funtoo/etc/zfs | # ##i##mkdir -p /mnt/funtoo/etc/zfs | ||
| Line 173: | Line 186: | ||
}} | }} | ||
You | You will also want to copy over {{f|resolv.conf}} in order to have proper resolution of Internet hostnames from inside the chroot: | ||
{{console|body= | {{console|body= | ||
# ##i##cp /etc/resolv.conf /mnt/funtoo/etc/ | # ##i##cp /etc/resolv.conf /mnt/funtoo/etc/ | ||
}} | }} | ||
We are ready to <code>chroot</code> | We are now ready to <code>chroot</code>. | ||
{{console|body= | {{console|body= | ||
| Line 185: | Line 198: | ||
}} | }} | ||
Configure your system according to the main Install | ==Configuring your system== | ||
Configure your system according to the main [[Install|install guide]]. During startup, ZFS filesystems will be mounted '''without''' needing any entries in {{f|/etc/fstab}}. Comment out all entries in {{f|/etc/fstab}} except for partitions such as CD-ROMs, tmpfs, etc., if used. | |||
If you created a '''swap''' volume earlier, add an appropriate entry to {{f|/etc/fstab}}. | |||
{{console|body= | |||
# ##i## echo /dev/zvol/rpool/swap none swap defaults 0 0 >> /etc/fstab | |||
}} | |||
Note that swap on ZFS is unstable. If you decide to use swap, please take following into account: | |||
always use long <code>/dev/zvol</code> aliases in configuration files. Never use a short <code>/dev/zdX</code> device name. | |||
Next, update the portage tree: | Next, update the portage tree: | ||
{{console|body= | {{console|body= | ||
###i## | ###i## ego sync | ||
###i## env-update | ###i## env-update | ||
###i## source /etc/profile | ###i## source /etc/profile | ||
| Line 196: | Line 217: | ||
== Installing ZFS userspace and bootloader== | == Installing ZFS userspace and bootloader== | ||
=== Installing the ZFS userspace tools and kernel modules === | === Installing the ZFS userspace tools and kernel modules === | ||
Install the ZFS packages and sync the portage tree, if required: | |||
Install the ZFS packages | |||
{{console|body= | {{console|body= | ||
###i## | ###i## ego sync | ||
###i## emerge --ask sys-fs/zfs | ###i## emerge --ask sys-fs/zfs | ||
}} | }} | ||
Once successfully merged, add the following services to the boot runlevel of OpenRC: | Once it has successfully merged, add the following services to the boot runlevel of OpenRC: | ||
{{console|body= | {{console|body= | ||
###i## rc-update add zfs-import boot | ###i## rc-update add zfs-import boot | ||
###i## rc-update add zfs-mount boot | ###i## rc-update add zfs-mount boot | ||
}} | }} | ||
Add another two services | Add another two services to the default runlevel: | ||
{{console|body= | {{console|body= | ||
###i## rc-update add zfs-share default | ###i## rc-update add zfs-share default | ||
| Line 233: | Line 236: | ||
=== Create a ZFS-friendly initramfs === | === Create a ZFS-friendly initramfs === | ||
The Funtoo stage3 includes a linux kernel and initramfs. The initramfs is designed to mount and start Funtoo Linux on a variety of file systems. The initramfs contained within the stage3 will | The Funtoo stage3 includes a linux kernel and initramfs. The initramfs is designed to mount and start Funtoo Linux on a variety of file systems. The initramfs contained within the stage3 will '''not''' mount and start Funtoo in our ZFS storage pool. We must create an updated 'ZFS-friendly' initramfs. | ||
Optional: Update to the latest {{package|sys-kernel/genkernel}}: | Optional: Update to the latest {{package|sys-kernel/genkernel}}: | ||
| Line 240: | Line 243: | ||
}} | }} | ||
Use {{c|genkernel}} to create an initramfs capable of mounting our ZFS Storage Pool via the {{c|--zfs}} switch. Adjust {{c|--makeopts}} according to | Use {{c|genkernel}} to create an initramfs capable of mounting our ZFS Storage Pool via the {{c|--zfs}} switch. Adjust {{c|--makeopts}} according to the number of available threads: | ||
{{console|body= | {{console|body= | ||
# ##i##genkernel initramfs --no-clean --no-mountboot --makeopts=-j4 --kernel-config=/usr/src/linux/.config --zfs | # ##i##genkernel initramfs --no-clean --no-mountboot --makeopts=-j4 --kernel-config=/usr/src/linux/.config --zfs | ||
| Line 273: | Line 276: | ||
}} | }} | ||
Confirm the presence of the new initramfs: | |||
{{console|body= | {{console|body= | ||
###i## ls /boot/*genkernel* | ###i## ls /boot/*genkernel* | ||
/boot/initramfs-genkernel-x86_64-4.5.2-1 | /boot/initramfs-genkernel-x86_64-4.5.2-1 | ||
}} | |||
Grub expects the initramfs filename to be of the form: <code>initramfs-${KNAME}-${ARCH}-${KV}</code>. This guide assumes the usage of debian-sources. Tailor it to your specific kernel name, platform, and kernel version. Forgetting to rename <code>initramfs-genkernel</code> to <code>initramfs-debian-sources</code> will render the system unbootable. | |||
{{console|body= | |||
###i## cd /boot | |||
###i## mv initramfs-genkernel-x86_64-4.5.2-1 initramfs-debian-sources-x86_64-4.5.2-1 | |||
###i## ls /boot/*initramfs* | |||
/boot/initramfs-debian-sources-x86_64-4.5.2-1 | |||
}} | }} | ||
=== Installing GRUB 2 === | === Installing GRUB 2 === | ||
GRUB 2 must be built with support for ZFS Storage Pools on a single disk. This is achieved using the 'libzfs' USE flag. | GRUB 2 must be built with support for ZFS Storage Pools on a single disk. This is achieved using the 'libzfs' USE flag. | ||
<console> | |||
# ##i##echo "sys-boot/grub libzfs" >> /etc/portage/package.use | |||
</console> | |||
{{Note|If you have defined GRUB_PLATFORMS in your {{f|/etc/portage/make.conf}}, please ensure that it includes 'pc': e.g. GRUB_PLATFORMS{{=}}"efi-64 pc". | |||
This is required for booting in BIOS (non-UEFI) mode, as described in this guide.}} | |||
Now, install GRUB: | |||
<console> | <console> | ||
# ##i##emerge grub | # ##i##emerge grub | ||
</console> | </console> | ||
=== Configuring the Bootloader === | === Configuring the Bootloader === | ||
When {{c|zpool}} created our storage pool (rpool), it created partitions under a GPT scheme. In order to boot Funtoo Linux on a GPT partion under legacy (BIOS) boot, <code>sys-boot/grub</code> requires a small partition, called BIOS boot partition. By design, ZFS ({{c|zpool}}) left a very small unpartitioned space at the beginning of the disk. We will use <code>sgdisk</code>, which is part of <code>sys-apps/gptfdisk</code> to format this free space into a BIOS boot partition. | When {{c|zpool}} created our storage pool (rpool), it created partitions under a GPT scheme. In order to boot Funtoo Linux on a GPT partion under legacy (BIOS) boot, <code>sys-boot/grub</code> requires a small partition, called a BIOS boot partition. By design, ZFS ({{c|zpool}}) left a very small unpartitioned space at the beginning of the disk. We will use <code>sgdisk</code>, which is part of <code>sys-apps/gptfdisk</code>, to format this free space into a BIOS boot partition. | ||
{{console|body= | |||
###i## sgdisk -a1 -n2:48:2047 -t2:EF02 -c2:"BIOS boot partition" /dev/disk/by-id/ata-Samsung_SSD_840_EVO_120GB_123456789ABCDEF | |||
}} | |||
To avoid problems with GRUB, use {{c|partx}} to refresh the list of partitions that are 'seen' by the kernel. Do this for each drive (/dev/sda, /dev/sdb, etc.). | |||
{{console|body= | {{console|body= | ||
###i## | ###i## partx -u /dev/sda | ||
}} | }} | ||
| Line 308: | Line 331: | ||
}} | }} | ||
Now it's time for us to create grub's configuration file. First we must edit a few GRUB 2 settings in {{f|/etc/default/grub}}: | Now, it's time for us to create grub's configuration file. First, we must edit a few GRUB 2 settings in {{f|/etc/default/grub}}: | ||
{{important|The following is required to boot Funtoo Linux on ZFS!}} | {{important|The following is required to boot Funtoo Linux on ZFS!}} | ||
Replace the line | Replace the line | ||
| Line 319: | Line 342: | ||
}} | }} | ||
Now, create GRUB 2 configuration file: | |||
{{console|body= | {{console|body= | ||
###i## grub-mkconfig -o /boot/grub/grub.cfg | ###i## grub-mkconfig -o /boot/grub/grub.cfg | ||
| Line 331: | Line 349: | ||
Found initrd image: /boot/initramfs-genkernel-x86_64-4.5.2-1 | Found initrd image: /boot/initramfs-genkernel-x86_64-4.5.2-1 | ||
done | done | ||
}} | |||
If grub-mkconfig cannot find the initrd image, manually add initrd to the generated {{c|/boot/grub/grub.cfg}}, below the linux line: | |||
{{file|name=/boot/grub/grub.cfg|desc=adding initrd below the linux line|body= | |||
echo 'Loading Linux x86_64-4.5.2-1 ...' | |||
linux /ROOT/funtoo@/boot/kernel-debian-sources-x86_64-4.5.2-1 root=ZFS=rpool/ROOT/funtoo ro dozfs real_root=ZFS | |||
echo 'Loading initial ramdisk ...' | |||
initrd /ROOT/funtoo@/boot/initramfs-debian-sources-x86_64-4.5.2-1 | |||
}} | }} | ||
| Line 340: | Line 366: | ||
== Final configuration == | == Final configuration == | ||
Configure your | Configure your network according to the main [[Install#Configuring_your_network|installation guide]]. | ||
Set the root password. | Set the root password. | ||
| Line 347: | Line 373: | ||
}} | }} | ||
Exit the chroot and export your ZFS | Exit the chroot and export your ZFS storage pool. | ||
{{console|body= | {{console|body= | ||
(chroot) ###i## exit | (chroot) ###i## exit | ||
| Line 355: | Line 381: | ||
}} | }} | ||
Restart to boot into Funtoo Linux on ZFS | Restart to boot into Funtoo Linux on a ZFS root! | ||
== After reboot == | == After reboot == | ||
| Line 363: | Line 389: | ||
###i## zfs snapshot rpool/ROOT/funtoo@install | ###i## zfs snapshot rpool/ROOT/funtoo@install | ||
}} | }} | ||
The use of snapshots, including sending snapshots as a method of backup, are not covered in this guide. See [[ZFS_Install_Guide#Further_Reading|Further Reading]]. | |||
===ZFS Adjustable Replacement Cache (ARC) size=== | |||
The Adjustable Replacement Cache (ARC) is a fundamental part of ZFS. Refer to this [https://pthree.org/2012/12/07/zfs-administration-part-iv-the-adjustable-replacement-cache%20link article] by Aaron Toponce for details on how to set up an ARC. | |||
Without configuration, ZFS will use up to 50% of your memory (RAM) for the ARC. It is possible to change this maximum. There are different ways to achieve this on both a temporary and persistent basis. One such way is to create and edit the file {{f|/etc/modprobe.d/zfs.conf}}, which affects the ZFS kernel module. | |||
{{file|name=/etc/modprobe.d/zfs.conf|desc=set maximum ARC size to 4 GiB|body= | |||
options zfs zfs_arc_max=4294967296 | |||
}} | |||
where {{c|zfs_arc_max}} is set to a value in Bytes. After configuring this file, re-generate the initramfs. Rebooting will then apply this change. | |||
To apply this change immediately without a reboot, issue the command: | |||
{{console|body= | |||
# ##i## echo 4294967296 >> /sys/module/zfs/parameters/zfs_arc_max | |||
}} | |||
Reference: https://wiki.gentoo.org/wiki/ZFS#ARC | |||
===After Kernel or ZFS updates=== | ===After Kernel or ZFS updates=== | ||
{{ | The default Funtoo Linux kernel ({{package|sys-kernel/debian-sources}}) does not automatically build a ZFS-capable initramfs. Similarly, the package {{c|sys-fs/zfs}} and its dependencies do not automatically build a ZFS-capable initramfs. | ||
{{ | |||
After each kernel update, you must recreate an initramfs. Similarly, {{c|sys-fs/zfs}} updates also require you to regenerate an initramfs. This is especially true for updates to {{c|sys-fs/zfs}} that introduce new storage pool features. Neglecting to update your initramfs will make your system unbootable. | |||
First, rebuild {{c|sys-fs/zfs}}, {{c|sys-fs/zfs-kmod}} and {{c|sys-kernel/spl}}: | |||
{{console|body= | |||
# ##i##emerge --ask --verbose -1 zfs zfs-kmod spl | |||
}} | |||
Then, follow the earlier instructions to create a new initramfs: | |||
{{console|body= | |||
# ##i##genkernel initramfs --no-clean --no-mountboot --makeopts=-j4 --kernel-config=/usr/src/linux/.config --zfs | |||
# ##i##cd /boot | |||
# ##i##mv initramfs-genkernel-x86_64-4.5.2-1 initramfs-debian-sources-x86_64-4.5.2-1 | |||
}} | |||
Finally, repeat the earlier instructions for generating {{c|/boot/grub/grub.cfg}} and manually adding the new initramfs as initrd to the generated {{c|/boot/grub/grub.cfg}}. | |||
== Further Reading == | == Further Reading == | ||
ZFS has many interesting features not covered by this guide. | |||
Useful information and instructions can be found in the online reference manuals. See {{c|man zpool}} and {{c|man zfs}}. | |||
Aaron Toponce's Zpool/ZFS Administration Guides - https://pthree.org/2012/12/04/zfs-administration-part-i-vdevs | |||
ZFS on Linux - http://www.zfsonlinux.org | ZFS on Linux - http://www.zfsonlinux.org | ||
ZFS - Gentoo Wiki - https://wiki.gentoo.org/wiki/ZFS | ZFS - Gentoo Wiki - https://wiki.gentoo.org/wiki/ZFS | ||
== Troubleshooting == | == Troubleshooting == | ||
=== Forgot to reset password? === | === Forgot to reset password? === | ||
You will need to chroot into your Funtoo on ZFS root installation if you forgot to set the root password. Repeat the earlier instructions to load the the live CD/USB, including the installation of ZFS kernel modules. | |||
When the ZFS kernel modules are loaded, your existing ZFS Storage Pool (rpool) will be imported automatically. This will also result in an attempt to mount the various ZFS filesystems that you created. Mounting your root partition (/) will fail since this location is not empty; / is allocated to the live CD/USB distribution! | |||
{{console|body= | {{console|body= | ||
###i## zpool status | ###i## zpool status | ||
| Line 399: | Line 458: | ||
}} | }} | ||
To get around this issue, first, manually export the pool. | |||
{{console|body= | {{console|body= | ||
###i## zpool export rpool | ###i## zpool export rpool | ||
| Line 406: | Line 465: | ||
}} | }} | ||
Now, import your storage pool using the following command. | |||
{{console|body= | {{console|body= | ||
###i## zpool import -o cachefile=/tmp/zpool.cache -R /mnt/funtoo -d /dev/disk/by-id/ rpool | ###i## zpool import -o cachefile=/tmp/zpool.cache -R /mnt/funtoo -d /dev/disk/by-id/ rpool | ||
}} | }} | ||
This will import rpool and place your Funtoo install at {{f|/mnt/funtoo}}. Follow the earlier set of instructions to chroot into your Funtoo Installation on ZFS root. | |||
=== Will not mount on first reboot? === | |||
Follow the above instructions on "Forgot to reset password?" to import and mount your storage pool (rpool) and chroot back into your Funtoo environment. | |||
Things to check: | |||
* Was the ''bootfs'' property of rpool set? Use {{c|zpool get bootfs rpool}} to check | |||
* Was /tmp/zpool.cache copied into /mnt/funtoo/etc/zfs/ prior to chroot and creating the initramfs? | |||
* Was {{c|genkernel initramfs}} run with the --zfs switch and --kernel-config pointing to the correct configuration file? | |||
* Was GRUB installed and configured correctly? | |||
=== rpool is 'busy' on zpool export === | |||
This happens when swapon is used. | |||
Swap must be turned off to free the pool for export. | |||
=== | === Unable to add universe repository in Ubuntu? === | ||
See http://askubuntu.com/questions/761592/unable-to-apt-get-dist-upgrade-on-a-persistent-ubuntu-16-04-usb | |||
[[Category:HOWTO]] | [[Category:HOWTO]] | ||
[[Category:Filesystems]] | [[Category:Filesystems]] | ||
__NOTITLE__ | __NOTITLE__ | ||
Latest revision as of 09:35, September 16, 2023
This page is unofficial. ZFS as root filesystem is not supported under Funtoo Linux, mainly because it has limited benefit. ZFS is still supported but boot on a non-ZFS filesystem first. See ZFS.
Introduction
This wiki article will show you how to install Funtoo on ZFS (rootfs).
Prerequisites
ZFS is designed for 64-bit systems. We only recommend and support 64-bit platforms and installations!
ZFS v07.5 (latest in ports as of 18 Jan 2018) is compatible with kernel versions 2.6.32 - 4.14
The guide is under rewrite
It is recommended to give the entire disk to ZFS. As such, this guide will only show how to install ZFS on the whole disk, using legacy boot. Installing on UEFI requires a separate partition for /boot, formatted as FAT32, and is out of the scope of this guide, even though installation on UEFI is certainly possible. Also, this guide will not cover anything related to encryption (native encryption is available: https://github.com/zfsonlinux/zfs/commit/b52563034230b35f0562b6f40ad1a00f02bd9a05).
Downloading the ISO (With ZFS)
In order to install Funtoo on ZFS, you will need an environment, such as live media, that provides the ZFS tools. This guide will utilize the Ubuntu Desktop 16.04 (live) DVD for amd64.
- Download from [1]
Creating a bootable USB from ISO (From a Linux Environment)
After you download the iso, you can do the following steps to create a bootable USB:
The size of the iso is approximately 1.5 GB.
Insert your blank USB media into a USB port. Then, inspect the kernel ring buffer with dmesg to identify the device name of your USB storage.
[ +5.533491] usb 6-2: new SuperSpeed USB device number 4 using xhci_hcd [ +0.022995] usb 6-2: New USB device found, idVendor=1b1c, idProduct=1a0c [ +0.000006] usb 6-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3 [ +0.000003] usb 6-2: Product: Voyager Mini 3.0 [ +0.000003] usb 6-2: Manufacturer: Corsair [ +0.000002] usb 6-2: SerialNumber: 0123456789ABCDEF [ +0.001095] usb-storage 6-2:1.0: USB Mass Storage device detected [ +0.000080] scsi host15: usb-storage 6-2:1.0 [ +1.000772] scsi 15:0:0:0: Direct-Access Corsair Voyager Mini 3.0 PMAP PQ: 0 ANSI: 6 [ +0.000615] sd 15:0:0:0: Attached scsi generic sg6 type 0 [ +0.000110] sd 15:0:0:0: [sdg] 60566016 512-byte logical blocks: (31.0 GB/28.9 GiB) [ +0.000209] sd 15:0:0:0: [sdg] Write Protect is off [ +0.000004] sd 15:0:0:0: [sdg] Mode Sense: 2b 00 00 08 [ +0.000227] sd 15:0:0:0: [sdg] Write cache: disabled, read cache: enabled, doesn't support DPO or FUA [ +0.359532] sd 15:0:0:0: [sdg] Attached SCSI removable disk
In this example, [sdg] indicates that the device is /dev/sdg.
A quick and easy way to create a bootable USB is to write the ISO data to the USB device using dd.
root # dd if=/path/to/iso/ubuntu-16.04-desktop-amd64.iso of=/dev/sdg bs=4K
Once this has completed, remove and use this USB to boot the target system that will receive Funtoo Linux.
Booting the ISO
Using legacy (BIOS) boot mode, boot the ISO and allow Ubuntu to load the graphical environment. You will be presented with a "Welcome" dialog (titled Install (as superuser)). Select the option "Try Ubuntu".
Once the desktop has loaded, open the search bar by left-clicking on the top-left icon ("Search your computer"). Pressing Alt+F1 should also open this search bar. Search for and open the Terminal application.
In the terminal, issue the following commands to install and load the required ZFS module.
ubuntu@ubuntu:~$ sudo -i root@ubuntu:~# apt-add-repository universe root@ubuntu:~# apt update root@ubuntu:~# apt install --yes debootstrap gdisk zfs-initramfs
Verify that the ZFS kernel module has loaded.
root@ubuntu:~# dmesg | grep ZFS [ 377.595348] ZFS: Loaded module v0.6.5.6-0ubuntu10, ZFS pool version 5000, ZFS filesystem version 5
Drive Partitions
We are letting ZFS automatically partition the drive. This is ideal for our example using a single disk and legacy (BIOS) boot.
Creating of pool
Create a ZFS Storage Pool using a single whole disk.
root@ubuntu:~# zpool create -d -o feature@async_destroy=enabled -o feature@empty_bpobj=enabled -o feature@lz4_compress=enabled -o feature@spacemap_histogram=enabled -o feature@enabled_txg=enabled -o feature@extensible_dataset=enabled -o feature@bookmarks=enabled -f -o ashift=12 -o cachefile=/tmp/zpool.cache -O normalization=formD -O atime=off -O xattr=sa -O compression=lz4 -m none -R /mnt/funtoo rpool /dev/disk/by-id/foo
The options used here are
| option | description |
|---|---|
create | Use zpool to create a ZFS Storage Pool. |
-d | Required. Disables enabling all availabe zfs features. This is needed as the GRUB bootloader currently can't handle all advanced zfs features, not specifying this flag on pool creation (or running 'zpool upgrade' on the pool at a later point in time) will make the pool incompatible with GRUB. |
(multiple) -o feature@<name>=enabled | Explicitely enable all features currently supported by GRUB. See 'man zpool-features' for details on their effects. |
-f | Force the use of the selected disk. |
-o ashift=12 | Alignment of the pool to underlying hard drive sectors. The recommended value is 12, which corresponds to 2^12 Bytes or 4 KiB. This value is typical for present-day HDD's. Can only be set once at pool creation. |
-o cachefile=/tmp/zpool.cache | Create a pool configuration cache and place it in /tmp. This will be required for our Funtoo install. |
-O normalization=formD | Recommended. Set the default Unicode (UTF-8) normalization for future filesystems (created within this pool) to 'formD'. |
-O atime=off | Recommended. As a default preference, set future filesystems (created within this pool) to not update file access time. Useful if we want to reduce writes to disk (e.g., Solid State Drives). Can cause problems for mailers and other software that rely on file access-time data. |
-O xattr=sa | Recommended. As a default preference, set future filesystems (created within this pool) to store extended file attributes in a more efficient manner. |
-O compression=lz4 | Recommended. As a default preference, set future filesystems (created within this pool) to be compressed using the lz4 algorithm. Useful in general as the runtime cost for compression is neglible on these days while on-disk space still costs money. |
-m none | Do not set mountpoint for this storage pool. (This guide will address this later). |
-R /mnt/funtoo | Alternate root directory. Essentially a temporary 'mount point' for our pool. |
rpool | The name of this ZFS Storage Pool. The pool name is irrelevant. rpool will be used throughout this guide. |
/dev/disk/by-id/foo | The path to the physical disk. e.g. /dev/disk/by-id/ata-Samsung_SSD_840_EVO_120GB_123456789ABCDEF. Known in 'ZFS-speak' as a 'VDEV'. |
Please note that the options 'ashift' and 'cachefile' are preceded with a lowercase '-o', while 'normalization' and 'atime' are preceded with an uppercase '-O'.
Without additional options, this will create our storage pool and enable all 'features' available under version 0.6.5.6. The pool will be automatically mounted at the (temporary) location /mnt/funtoo.
To confirm the presence of our newly created pool:
root@ubuntu:~# zpool status
pool: rpool
state: ONLINE
scan: none requested
config:
NAME STATE READ WRITE CKSUM
rpool ONLINE 0 0 0
ata-Samsung_SSD_840_EVO_120GB_123456789ABCDEF ONLINE 0 0 0
errors: No known data errors
Create ZFS Datasets
Now, we will create one or more ZFS datasets within our storage pool. These will contain Funtoo Linux.
Create the Root file system (Required)
root # zfs create -o mountpoint=none -o canmount=off rpool/ROOT root # zfs create -o mountpoint=/ rpool/ROOT/funtoo
Create optional Datasets
The following optional datasets are provided as examples. It is up to the user to create their own datasets.
Home
root # zfs create -o mountpoint=/home rpool/HOME
Build directory
root # zfs create -o mountpoint=none -o canmount=off rpool/FUNTOO root # zfs create -o mountpoint=/var/tmp/portage -o compression=lz4 -o sync=disabled rpool/FUNTOO/build
Swap on ZFS
With some careful tuning a swap partition can be created on a ZFS 'volume' [2]. For a 2 GB swapfs:
root # zfs create -V 2G -b $(getconf PAGESIZE) -o logbias=throughput -o sync=always -o primarycache=metadata rpool/swap root # mkswap /dev/zvol/rpool/swap root # swapon /dev/zvol/rpool/swap
Note that swap on ZFS has known stability issues. If the user has decided to use swap, please take following into account:
Always use long /dev/zvol aliases in configuration files. Never use a short /dev/zdX device name.
To confirm the presence of the filesystems that we have created:
root@ubuntu:~# zfs list -t all
NAME USED AVAIL REFER MOUNTPOINT
rpool 660K 19.3G 96K none
rpool/HOME 96K 19.3G 96K /mnt/funtoo/home
rpool/ROOT 192K 19.3G 96K none
rpool/ROOT/funtoo 96K 19.3G 96K /mnt/funtoo
Make the root filesystem bootable
Do not skip this!
When booting from ZFS, you must specify a boot device and a root file system within the pool that was identified by the boot device. By default, the dataset selected for booting is the one identified by the pool's bootfs property.
root # zpool set bootfs=rpool/ROOT/funtoo rpool
Installing Funtoo
Now that the initial ZFS pool and datasets have been created, we can unpack the stage 3 tarball and proceed with basic system installation. This part does not differ much from a regular Funtoo Linux installation (https://www.funtoo.org/Install#Installing_the_Stage_3_tarball). We recommend using funtoo-current stages for ZFS.
root # cd /mnt/funtoo root # wget https://build.funtoo.org/next/x86-64bit/generic_64/stage3-latest.tar.xz
Extract the contents with the following command. If the user is using an arch-optimized stage 3 tarball, substitute in the actual filename.
root # cd /mnt/funtoo root # tar xpf stage3-latest.tar.xz
Now, we need to create a chroot environment:
root # cd /mnt/funtoo root # mount -t proc none proc root # mount --rbind /sys sys root # mount --rbind /dev dev
An important step is to copy the ZFS cache into the chroot. The ZFS cache was created when rpool was created with the -o cachefile=/tmp/zpool.cache flag.
root # mkdir -p /mnt/funtoo/etc/zfs root # cp /tmp/zpool.cache /mnt/funtoo/etc/zfs/zpool.cache
You will also want to copy over resolv.conf in order to have proper resolution of Internet hostnames from inside the chroot:
root # cp /etc/resolv.conf /mnt/funtoo/etc/
We are now ready to chroot.
root # chroot /mnt/funtoo /bin/bash root # export PS1="(chroot) $PS1"; cd
Configuring your system
Configure your system according to the main install guide. During startup, ZFS filesystems will be mounted without needing any entries in /etc/fstab. Comment out all entries in /etc/fstab except for partitions such as CD-ROMs, tmpfs, etc., if used.
If you created a swap volume earlier, add an appropriate entry to /etc/fstab.
root # echo /dev/zvol/rpool/swap none swap defaults 0 0 >> /etc/fstab
Note that swap on ZFS is unstable. If you decide to use swap, please take following into account:
always use long /dev/zvol aliases in configuration files. Never use a short /dev/zdX device name.
Next, update the portage tree:
root # ego sync root # env-update root # source /etc/profile
Installing ZFS userspace and bootloader
Installing the ZFS userspace tools and kernel modules
Install the ZFS packages and sync the portage tree, if required:
root # ego sync root # emerge --ask sys-fs/zfs
Once it has successfully merged, add the following services to the boot runlevel of OpenRC:
root # rc-update add zfs-import boot root # rc-update add zfs-mount boot
Add another two services to the default runlevel:
root # rc-update add zfs-share default root # rc-update add zfs-zed default
Create a ZFS-friendly initramfs
The Funtoo stage3 includes a linux kernel and initramfs. The initramfs is designed to mount and start Funtoo Linux on a variety of file systems. The initramfs contained within the stage3 will not mount and start Funtoo in our ZFS storage pool. We must create an updated 'ZFS-friendly' initramfs.
Optional: Update to the latest No results:
root # emerge --oneshot sys-kernel/genkernel
Use genkernel to create an initramfs capable of mounting our ZFS Storage Pool via the --zfs switch. Adjust --makeopts according to the number of available threads:
root # genkernel initramfs --no-clean --no-mountboot --makeopts=-j4 --kernel-config=/usr/src/linux/.config --zfs root ##g##* Funtoo Linux Genkernel; Version 3.4.40.11-funtoo##!g## root ##g##*##!g## Running with options: initramfs --no-clean --no-mountboot --makeopts=-j4 --kernel-config=/usr/src/linux/.config --zfs root ##g##*##!g## Linux Kernel 4.5.2-1 for x86_64... root ##g##*##!g## .. with config file /usr/src/linux-debian-sources-4.5.2/.config root ##g##*##!g## busybox: >> Using cache root ##g##*##!g## initramfs: >> Initializing... root ##g##*##!g## >> Appending base_layout cpio data... root ##g##*##!g## >> Appending auxilary cpio data... root ##g##*##!g## >> Copying keymaps root ##g##*##!g## >> Appending busybox cpio data... root ##g##*##!g## >> Appending modules cpio data... root ##g##*##!g## >> Appending zfs cpio data... cp: cannot stat ‘/etc/zfs/zdev.conf’: No such file or directory root ##y##*##!y## Could not copy file /etc/zfs/zdev.conf for ZFS root ##g##*##!g## >> Appending blkid cpio data... root ##g##*##!g## >> Appending modprobed cpio data... root ##g##*##!g## >> Compressing cpio data (.xz)... root ##y##*##!y## WARNING... WARNING... WARNING... root ##y##*##!y## Additional kernel cmdline arguments that *may* be required to boot properly... root ##y##*##!y## add "dozfs" for ZFS volume management support root ##y##*##!y## add either "real_root=ZFS" (bootfs autodetection) or "real_root=ZFS=<dataset>" to boot from a ZFS dataset root ##g##*##!g## Do NOT report kernel bugs as genkernel bugs unless your bug root ##g##*##!g## is about the default genkernel configuration... root ##g##*##!g## root ##g##*##!g## Make sure you have the latest ~arch genkernel before reporting bugs.
Confirm the presence of the new initramfs:
root # ls /boot/*genkernel* /boot/initramfs-genkernel-x86_64-4.5.2-1
Grub expects the initramfs filename to be of the form: initramfs-${KNAME}-${ARCH}-${KV}. This guide assumes the usage of debian-sources. Tailor it to your specific kernel name, platform, and kernel version. Forgetting to rename initramfs-genkernel to initramfs-debian-sources will render the system unbootable.
root # cd /boot root # mv initramfs-genkernel-x86_64-4.5.2-1 initramfs-debian-sources-x86_64-4.5.2-1 root # ls /boot/*initramfs* /boot/initramfs-debian-sources-x86_64-4.5.2-1
Installing GRUB 2
GRUB 2 must be built with support for ZFS Storage Pools on a single disk. This is achieved using the 'libzfs' USE flag.
root # echo "sys-boot/grub libzfs" >> /etc/portage/package.use
If you have defined GRUB_PLATFORMS in your /etc/portage/make.conf, please ensure that it includes 'pc': e.g. GRUB_PLATFORMS="efi-64 pc".
This is required for booting in BIOS (non-UEFI) mode, as described in this guide.
Now, install GRUB:
root # emerge grub
Configuring the Bootloader
When zpool created our storage pool (rpool), it created partitions under a GPT scheme. In order to boot Funtoo Linux on a GPT partion under legacy (BIOS) boot, sys-boot/grub requires a small partition, called a BIOS boot partition. By design, ZFS (zpool) left a very small unpartitioned space at the beginning of the disk. We will use sgdisk, which is part of sys-apps/gptfdisk, to format this free space into a BIOS boot partition.
root # sgdisk -a1 -n2:48:2047 -t2:EF02 -c2:"BIOS boot partition" /dev/disk/by-id/ata-Samsung_SSD_840_EVO_120GB_123456789ABCDEF
To avoid problems with GRUB, use partx to refresh the list of partitions that are 'seen' by the kernel. Do this for each drive (/dev/sda, /dev/sdb, etc.).
root # partx -u /dev/sda
A quick check to verify that GRUB 2 sees/supports ZFS:
root # touch /etc/mtab root # grub-probe / zfs
Installing GRUB2 to disk is as easy as:
root # grub-install /dev/disk/by-id/ata-Samsung_SSD_840_EVO_120GB_123456789ABCDEF Installing for i386-pc platform. Installation finished. No error reported.
Now, it's time for us to create grub's configuration file. First, we must edit a few GRUB 2 settings in /etc/default/grub:
The following is required to boot Funtoo Linux on ZFS!
Replace the line
/etc/default/grub - before#GRUB_CMDLINE_LINUX=""
with
/etc/default/grub - afterGRUB_CMDLINE_LINUX="dozfs real_root=ZFS=rpool/ROOT/funtoo"
Now, create GRUB 2 configuration file:
root # grub-mkconfig -o /boot/grub/grub.cfg Generating grub configuration file ... Found linux image: /boot/kernel-debian-sources-x86_64-4.5.2-1 Found initrd image: /boot/initramfs-genkernel-x86_64-4.5.2-1 done
If grub-mkconfig cannot find the initrd image, manually add initrd to the generated /boot/grub/grub.cfg, below the linux line:
/boot/grub/grub.cfg - adding initrd below the linux lineecho 'Loading Linux x86_64-4.5.2-1 ...'
linux /ROOT/funtoo@/boot/kernel-debian-sources-x86_64-4.5.2-1 root=ZFS=rpool/ROOT/funtoo ro dozfs real_root=ZFS
echo 'Loading initial ramdisk ...'
initrd /ROOT/funtoo@/boot/initramfs-debian-sources-x86_64-4.5.2-1
A quick check to verify that the GRUB ZFS module is in place:
root # ls /boot/grub/*/zfs.mod /boot/grub/i386-pc/zfs.mod
Final configuration
Configure your network according to the main installation guide.
Set the root password.
(chroot) # passwd
Exit the chroot and export your ZFS storage pool.
(chroot) # exit root # umount -lR {dev,proc,sys} root # cd / root # zpool export rpool
Restart to boot into Funtoo Linux on a ZFS root!
After reboot
Snapshot
Take a snapshot of your Funtoo at installation.
root # zfs snapshot rpool/ROOT/funtoo@install
The use of snapshots, including sending snapshots as a method of backup, are not covered in this guide. See Further Reading.
ZFS Adjustable Replacement Cache (ARC) size
The Adjustable Replacement Cache (ARC) is a fundamental part of ZFS. Refer to this article by Aaron Toponce for details on how to set up an ARC.
Without configuration, ZFS will use up to 50% of your memory (RAM) for the ARC. It is possible to change this maximum. There are different ways to achieve this on both a temporary and persistent basis. One such way is to create and edit the file /etc/modprobe.d/zfs.conf, which affects the ZFS kernel module.
/etc/modprobe.d/zfs.conf - set maximum ARC size to 4 GiBoptions zfs zfs_arc_max=4294967296
where zfs_arc_max is set to a value in Bytes. After configuring this file, re-generate the initramfs. Rebooting will then apply this change.
To apply this change immediately without a reboot, issue the command:
root # echo 4294967296 >> /sys/module/zfs/parameters/zfs_arc_max
Reference: https://wiki.gentoo.org/wiki/ZFS#ARC
After Kernel or ZFS updates
The default Funtoo Linux kernel (sys-kernel/debian-sources) does not automatically build a ZFS-capable initramfs. Similarly, the package sys-fs/zfs and its dependencies do not automatically build a ZFS-capable initramfs.
After each kernel update, you must recreate an initramfs. Similarly, sys-fs/zfs updates also require you to regenerate an initramfs. This is especially true for updates to sys-fs/zfs that introduce new storage pool features. Neglecting to update your initramfs will make your system unbootable.
First, rebuild sys-fs/zfs, sys-fs/zfs-kmod and sys-kernel/spl:
root # emerge --ask --verbose -1 zfs zfs-kmod spl
Then, follow the earlier instructions to create a new initramfs:
root # genkernel initramfs --no-clean --no-mountboot --makeopts=-j4 --kernel-config=/usr/src/linux/.config --zfs root # cd /boot root # mv initramfs-genkernel-x86_64-4.5.2-1 initramfs-debian-sources-x86_64-4.5.2-1
Finally, repeat the earlier instructions for generating /boot/grub/grub.cfg and manually adding the new initramfs as initrd to the generated /boot/grub/grub.cfg.
Further Reading
ZFS has many interesting features not covered by this guide.
Useful information and instructions can be found in the online reference manuals. See man zpool and man zfs.
Aaron Toponce's Zpool/ZFS Administration Guides - https://pthree.org/2012/12/04/zfs-administration-part-i-vdevs
ZFS on Linux - http://www.zfsonlinux.org
ZFS - Gentoo Wiki - https://wiki.gentoo.org/wiki/ZFS
Troubleshooting
Forgot to reset password?
You will need to chroot into your Funtoo on ZFS root installation if you forgot to set the root password. Repeat the earlier instructions to load the the live CD/USB, including the installation of ZFS kernel modules.
When the ZFS kernel modules are loaded, your existing ZFS Storage Pool (rpool) will be imported automatically. This will also result in an attempt to mount the various ZFS filesystems that you created. Mounting your root partition (/) will fail since this location is not empty; / is allocated to the live CD/USB distribution!
root # zpool status pool: rpool state: ONLINE scan: none requested config: NAME STATE READ WRITE CKSUM rpool ONLINE 0 0 0 ata-Samsung_SSD_840_EVO_120GB_123456789ABCDEF ONLINE 0 0 0 errors: No known data errors
To get around this issue, first, manually export the pool.
root # zpool export rpool root # zpool list no pools available
Now, import your storage pool using the following command.
root # zpool import -o cachefile=/tmp/zpool.cache -R /mnt/funtoo -d /dev/disk/by-id/ rpool
This will import rpool and place your Funtoo install at /mnt/funtoo. Follow the earlier set of instructions to chroot into your Funtoo Installation on ZFS root.
Will not mount on first reboot?
Follow the above instructions on "Forgot to reset password?" to import and mount your storage pool (rpool) and chroot back into your Funtoo environment.
Things to check:
- Was the bootfs property of rpool set? Use
zpool get bootfs rpoolto check - Was /tmp/zpool.cache copied into /mnt/funtoo/etc/zfs/ prior to chroot and creating the initramfs?
- Was
genkernel initramfsrun with the --zfs switch and --kernel-config pointing to the correct configuration file? - Was GRUB installed and configured correctly?
rpool is 'busy' on zpool export
This happens when swapon is used. Swap must be turned off to free the pool for export.
Unable to add universe repository in Ubuntu?