Difference between pages "VirtualBox" and "ZFS Install Guide"

From Funtoo
(Difference between pages)
Jump to: navigation, search
(Installation)
 
(Install the bootloader)
 
Line 1: Line 1:
<code>VirtualBox</code> is an application that allows to run a guest O/S inside a host O/S.
+
== Introduction ==
  
== Glossary of Terms ==
+
This tutorial will show you how to install Funtoo on ZFS (rootfs). This tutorial is meant to be an "overlay" over the [[Funtoo_Linux_Installation|Regular Funtoo Installation]]. Follow the normal installation and only use this guide for steps 2, 3, and 8.
  
:;Host O/S : system running on computer you are actually on;
+
=== Introduction to ZFS ===
:;Guest O/S : system indtalled within VirtualBox;
+
:;Guest Additions : drivers for the Guest O/S.
+
  
== Versions of VirtualBox ==
+
Since ZFS is a new technology for Linux, it can be helpful to understand some of its benefits, particularly in comparison to BTRFS, another popular next-generation Linux filesystem:
  
VirtualBox is available in two versions :
+
* On Linux, the ZFS code can be updated independently of the kernel to obtain the latest fixes. btrfs is exclusive to Linux and you need to build the latest kernel sources to get the latest fixes.
  
# '''Source based package''' : app-emulation/virtualbox;
+
* ZFS is supported on multiple platforms. The platforms with the best support are Solaris, FreeBSD and Linux. Other platforms with varying degrees of support are NetBSD, Mac OS X and Windows. btrfs is exclusive to Linux.
# '''Binary package''' : app-emeulation/virtualbox-bin.
+
  
Binary package contains extensions which are not available with the source one. When we install the source based package, we must refer to the USE flags list hereafter.
+
* ZFS has the Adaptive Replacement Cache replacement algorithm while btrfs uses the Linux kernel's Last Recently Used replacement algorithm. The former often has an overwhelmingly superior hit rate, which means fewer disk accesses.
  
== USE flags ==
+
* ZFS has the ZFS Intent Log and SLOG devices, which accelerates small synchronous write performance.
  
{| class="wikitable" style="margin-left: 1em; margin-right: 1em;" width=80%
+
* ZFS handles internal fragmentation gracefully, such that you can fill it until 100%. Internal fragmentation in btrfs can make btrfs think it is full at 10%. Btrfs has no automatic rebalancing code, so it requires a manual rebalance to correct it.
! width="20%" | Use flag
+
! width="10%" | Default
+
! width="10%" | Recommended
+
! width="60%" | Description
+
|-
+
| style="text-align:center;" |additions
+
| style="text-align:center;" |Yes
+
| style="text-align:center;" |Yes
+
| Install Guest System Tools ISO.
+
|-
+
| style="text-align:center;" |alsa
+
| style="text-align:center;" |Yes
+
| style="text-align:center;" |Yes
+
| Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture).
+
|-
+
| style="text-align:center;" |doc
+
| style="text-align:center;" |No
+
| style="text-align:center;" |
+
| Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally.
+
|-
+
| style="text-align:center;" |extensions
+
| style="text-align:center;" |No
+
| style="text-align:center;" |Yes
+
| Install extension module packages.
+
|-
+
| style="text-align:center;" |headless
+
| style="text-align:center;" |No
+
| style="text-align:center;" |
+
| Build without any graphic frontend.
+
|-
+
| style="text-align:center;" |java
+
| style="text-align:center;" |No
+
| style="text-align:center;" |No
+
| Add support for Java.
+
|-
+
| style="text-align:center;" |opengl
+
| style="text-align:center;" |Yes
+
| style="text-align:center;" |
+
| Add support for OpenGL (3D graphics).
+
|-
+
| style="text-align:center;" |pam
+
| style="text-align:center;" |Yes
+
| style="text-align:center;" |Yes
+
| Add support for PAM (Pluggable Authentication Modules) - DANGEROUS to arbitrarily flip.
+
|-
+
| style="text-align:center;" |pulseaudio
+
| style="text-align:center;" |Yes
+
| style="text-align:center;" |
+
| Add support for PulseAudio sound server.
+
|-
+
| style="text-align:center;" |python
+
| style="text-align:center;" |Yes
+
| style="text-align:center;" |
+
| Add optional support/bindings for the Python language.
+
|-
+
| style="text-align:center;" |python_single_target_python2_7
+
| style="text-align:center;" |Yes
+
| style="text-align:center;" |
+
| Build for Python 2.7 only.
+
|-
+
| style="text-align:center;" |python_targets_python2_7
+
| style="text-align:center;" |Yes
+
| style="text-align:center;" |
+
| Build with Python 2.7
+
|-
+
| style="text-align:center;" |qt4
+
| style="text-align:center;" |Yes
+
| style="text-align:center;" |Yes
+
| Add support for the Qt GUI/Application Toolkit version 4.x. No GUI when not set.
+
|-
+
| style="text-align:center;" |sdk
+
| style="text-align:center;" |Yes
+
| style="text-align:center;" |
+
| Enable building of SDK.
+
|-
+
| style="text-align:center;" |vboxwebsrv
+
| style="text-align:center;" |No
+
| style="text-align:center;" |No
+
| Build and install the VirtualBox webservice.
+
|-
+
| style="text-align:center;" |vnc
+
| style="text-align:center;" |No
+
| style="text-align:center;" |
+
| Enable VNC (remote desktop viewer) support.
+
|}
+
  
{{fancyimportant|Depending on desktop environment, some USE flags may already be set or unset. Set USE flags as per '''Recommended''' column when unset.}}
+
* ZFS has raidz, which is like RAID 5/6 (or a hypothetical RAID 7 that supports 3 parity disks), except it does not suffer from the RAID write hole issue thanks to its use of CoW and a variable stripe size. btrfs gained integrated RAID 5/6 functionality in Linux 3.9. However, its implementation uses a stripe cache that can only partially mitigate the effect of the RAID write hole.
  
== Installation ==
+
* ZFS send/receive implementation supports incremental update when doing backups. btrfs' send/receive implementation requires sending the entire snapshot.
  
{{fancyimportant|This tutorial deals with installation of source based package.}}
+
* ZFS supports data deduplication, which is a memory hog and only works well for specialized workloads. btrfs has no equivalent.
 +
 
 +
* ZFS datasets have a hierarchical namespace while btrfs subvolumes have a flat namespace.
 +
 
 +
* ZFS has the ability to create virtual block devices called zvols in its namespace. btrfs has no equivalent and must rely on the loop device for this functionality, which is cumbersome.
 +
 
 +
The only area where btrfs is ahead of ZFS is in the area of small file
 +
efficiency. btrfs supports a feature called block suballocation, which
 +
enables it to store small files far more efficiently than ZFS. It is
 +
possible to use another filesystem (e.g. reiserfs) on top of a ZFS zvol
 +
to obtain similar benefits (with arguably better data integrity) when
 +
dealing with many small files (e.g. the portage tree).
 +
 
 +
=== Disclaimers ===
 +
 
 +
{{fancywarning|This guide is a work in progress. Expect some quirks.}}
 +
{{fancyimportant|'''Since ZFS was really designed for 64 bit systems, we are only recommending and supporting 64 bit platforms and installations. We will not be supporting 32 bit platforms'''!}}
 +
 
 +
== Video Tutorial ==
 +
 
 +
As a companion to the installation instructions below, a YouTube video tutorial is now available:
 +
 
 +
{{#widget:YouTube|id=SWyThdxNoP8|width=640|height=360}}
 +
 
 +
{{fancyimportant|'''The video and guide are currently out of sync. The video has newer instructions. The guide needs to be updated.'''}}
 +
 
 +
== Downloading the ISO (With ZFS) ==
 +
In order for us to install Funtoo on ZFS, you will need an environment that already provides the ZFS tools. Therefore we will download a customized version of System Rescue CD with ZFS included.
 +
 
 +
<pre>
 +
Name: sysresccd-4.0.1_zfs_0.6.2.iso  (545 MB)
 +
Release Date: 2014-02-25
 +
md5sum 01f4e6929247d54db77ab7be4d156d85
 +
</pre>
 +
 
 +
 
 +
'''[http://ftp.osuosl.org/pub/funtoo/distfiles/sysresccd/ Download System Rescue CD with ZFS]'''<br />
 +
 
 +
== 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:
  
 
<console>
 
<console>
###i## echo ">=app-emulation/virtualbox-extpack-oracle-4.3.8 PUEL" >> /etc/portage/package.license/virtualbox
+
Make a temporary directory
###i## emerge app-emulation/virtualbox
+
# ##i##mkdir /tmp/loop
</console>
+
  
Installation of <code>app-emulation/virtualbox</code> implies <code>app-emulation/virtualbox-extpack-oracle</code>. That is why PUEL license must be enabled.
+
Mount the iso
 +
# ##i##mount -o ro,loop /root/sysresccd-4.0.1_zfs_0.6.2.iso /tmp/loop
  
== Guest Additions ==
+
Run the usb installer
 +
# ##i##/tmp/loop/usb_inst.sh
 +
</console>
  
Make sure that user running X session belongs to <code>vboxguest</code> group. Create group when it does not exist. Add user to the group. That will enable :
+
That should be all you need to do to get your flash drive working.
  
*Shared clipboard;
+
== Booting the ISO ==
*Display resizing;
+
 
*Seamless mode;
+
{{fancywarning|'''When booting into the ISO, Make sure that you select the "Alternate 64 bit kernel (altker64)". The ZFS modules have been built specifically for this kernel rather than the standard kernel. If you select a different kernel, you will get a fail to load module stack error message.'''}}
*Drag & Drop.
+
 
 +
== Creating partitions ==
 +
There are two ways to partition your disk: You can use your entire drive and let ZFS automatically partition it for you, or you can do it manually.
 +
 
 +
We will be showing you how to partition it '''manually''' because if you partition it manually you get to create your own layout, you get to have your own separate /boot partition (Which is nice since not every bootloader supports booting from ZFS pools), and you get to boot into RAID10, RAID5 (RAIDZ) pools and any other layouts due to you having a separate /boot partition.
 +
 
 +
==== gdisk (GPT Style) ====
 +
 
 +
'''A Fresh Start''':
 +
 
 +
First lets make sure that the disk is completely wiped from any previous disk labels and partitions.
 +
We will also assume that <tt>/dev/sda</tt> is the target drive.<br />
  
 
<console>
 
<console>
###i## groupadd vboxguest
+
# ##i##sgdisk -Z /dev/sda
###i## gpasswd -a ''user'' vboxguest
+
 
</console>
 
</console>
  
=== Windows Guests ===
+
{{fancywarning|This is a destructive operation and the program will not ask you for confirmation! Make sure you really don't want anything on this disk.}}
  
You must enable <code>additions</code> USE flag when you intend to install Windows as a guest O/S. That will also install the ISO image containing all necessary Windows guest drivrers.
+
Now that we have a clean drive, we will create the new layout.
  
=== Linux Guests ===
+
First open up the application:
  
If you want to run Funtoo GNU/Linux as a guest O/S, emerge <code>app-emulation/virtualbox-guest-additions</code> in the Funtoo GNU/Linux guest O/S. For other GNU/Linux, please refer to [https://www.virtualbox.org/manual/ch04.html#idp11274368 VirtualBox documentation].
+
<console>
 +
# ##i##gdisk /dev/sda
 +
</console>
  
== Post Installation ==
+
'''Create Partition 1''' (boot):
 +
<console>
 +
Command: ##i##n ↵
 +
Partition Number: ##i##↵
 +
First sector: ##i##↵
 +
Last sector: ##i##+250M ↵
 +
Hex Code: ##i##↵
 +
</console>
  
You will not be able to run and use VirtualBox as a regular user if you are not a member of the <code>vboxusers</code> group.
+
'''Create Partition 2''' (BIOS Boot Partition):
 +
<console>Command: ##i##n ↵
 +
Partition Number: ##i##↵
 +
First sector: ##i##↵
 +
Last sector: ##i##+32M ↵
 +
Hex Code: ##i##EF02 ↵
 +
</console>
 +
 
 +
'''Create Partition 3''' (ZFS):
 +
<console>Command: ##i##n ↵
 +
Partition Number: ##i##↵
 +
First sector: ##i##↵
 +
Last sector: ##i##↵
 +
Hex Code: ##i##bf00 ↵
 +
 
 +
Command: ##i##p ↵
 +
 
 +
Number  Start (sector)    End (sector)  Size      Code  Name
 +
  1            2048          514047  250.0 MiB  8300  Linux filesystem
 +
  2          514048          579583  32.0 MiB    EF02  BIOS boot partition
 +
  3          579584      1953525134  931.2 GiB  BF00  Solaris root
 +
 
 +
Command: ##i##w ↵
 +
</console>
 +
 
 +
 
 +
=== Format your /boot partition ===
  
 
<console>
 
<console>
###i## gpasswd -a ''user'' vboxusers
+
# ##i##mkfs.ext2 -m 1 /dev/sda1
 
</console>
 
</console>
  
You must re-log so changes take effect.
+
=== Encryption (Optional) ===
 +
If you want encryption, then create your encrypted vault(s) now by doing the following:
  
=== Loading Modules ===
+
<console>
 +
# ##i##cryptsetup luksFormat /dev/sda3
 +
# ##i##cryptsetup luksOpen /dev/sda3 vault_1
 +
</console>
  
Required and optional modules must be loaded before launching VirtualBox. You can do that as root or upon boot.
+
{{fancywarning|On some machines, a combination of ZFS and LUKS has caused instability and system crashes.}}
  
{{fancynote|<code>vboxnetadp</code> and <code>vboxnetflt</code> are optional.}}
+
=== Create the zpool ===
 +
We will first create the pool. The pool will be named `tank` and the disk will be aligned to 4096 (using ashift=12)
 +
<console># ##i##zpool create -f -o ashift=12 -o cachefile= -O compression=on -m none -R /mnt/funtoo tank /dev/sda3</console>
  
==== As root ====
+
{{fancyimportant|If you are using encrypted root, change '''/dev/sda3 to /dev/mapper/vault_1'''.}}
 +
 
 +
{{fancynote| If you have a previous pool that you would like to import, you can do a: '''zpool import -f -R /mnt/funtoo <pool_name>'''.}}
 +
 
 +
=== Create the zfs datasets ===
 +
We will now create some datasets. For this installation, we will create a small but future proof amount of datasets. We will have a dataset for the OS (/), and your swap. We will also show you how to create some optional datasets: <tt>/home</tt>, <tt>/var</tt>, <tt>/usr/src</tt>, and <tt>/usr/portage</tt>.
  
 
<console>
 
<console>
###i## modprobe vboxdrv
+
Create some empty containers for organization purposes, and make the dataset that will hold /
###i## modprobe vboxnetadp
+
# ##i##zfs create -p tank/funtoo
###i## modprobe vboxnetflt
+
# ##i##zfs create -o mountpoint=/ tank/funtoo/root
 +
 
 +
Optional, but recommended datasets: /home
 +
# ##i##zfs create -o mountpoint=/home tank/funtoo/home
 +
 
 +
Optional datasets: /usr/src, /usr/portage/{distfiles,packages}
 +
# ##i##zfs create -o mountpoint=/usr/src tank/funtoo/src
 +
# ##i##zfs create -o mountpoint=/usr/portage -o compression=off tank/funtoo/portage
 +
# ##i##zfs create -o mountpoint=/usr/portage/distfiles tank/funtoo/portage/distfiles
 +
# ##i##zfs create -o mountpoint=/usr/portage/packages tank/funtoo/portage/packages
 
</console>
 
</console>
  
==== Upon boot OpenRC ====
+
=== Create your swap zvol ===
 +
For modern machines that have greater than 4 GB of RAM, A swap size of 2G should be enough. However if your machine doesn't have a lot of RAM, the rule of thumb is either 2x the RAM or RAM + 1 GB.
  
Edit <code>/etc/conf.d/modules</code> :
+
For this tutorial we will assume that it is a newer machine and make a 2 GB swap.
  
<pre>modules="vboxdrv vboxnetadp vboxnetflt"</pre>
+
<console>
 +
# ##i##zfs create -o sync=always -o primarycache=metadata -o secondarycache=none -o volblocksize=4K -V 2G tank/swap
 +
</console>
  
==== Upon boot systemd ====
+
=== Format your swap zvol ===
 +
<console>
 +
# ##i##mkswap -f /dev/zvol/tank/swap
 +
# ##i##swapon /dev/zvol/tank/swap
 +
</console>
 +
 
 +
Now we will continue to install funtoo.
 +
 
 +
== Installing Funtoo ==
 +
 
 +
=== Pre-Chroot ===
  
 
<console>
 
<console>
###i## echo 'vboxdrv' >> /etc/modules-load.d/virtualbox.conf
+
Go into the directory that you will chroot into
###i## echo 'vboxnetadp' >> /etc/modules-load.d/virtualbox.conf
+
# ##i##cd /mnt/funtoo
###i## echo 'vboxnetflt' >> /etc/modules-load.d/virtualbox.conf
+
 
 +
Make a boot folder and mount your boot drive
 +
# ##i##mkdir boot
 +
# ##i##mount /dev/sda1 boot
 
</console>
 
</console>
  
=== Kernel Driver ===
+
[[Funtoo_Linux_Installation|Now download and extract the Funtoo stage3 ...]]
  
Each time a new kernel is installed, <code>vboxdrv</code> kernel module must be recompiled. To ensure Portage knows about that, look at <code>/var/lib/module-rebuild/moduledb</code>. The following record must be present.
+
Once you've extracted the stage3, do a few more preparations and chroot into your new funtoo environment:
  
<pre>a:1:app-emulation/virtualbox-modules-''version''</pre>
+
<console>
 +
Bind the kernel related directories
 +
# ##i##mount -t proc none proc
 +
# ##i##mount --rbind /dev dev
 +
# ##i##mount --rbind /sys sys
  
Running <code>emerge @module-rebuild</code> will recompile VirtualBox driver after installation of new kernel.
+
Copy network settings
 +
# ##i##cp -f /etc/resolv.conf etc
  
It is strongly recommended to install <code>sys-kernel<nowiki>/</nowiki>dkms</code>. This package keeps track of Linux kernel changes. It recompiles <code>vboxdrv</code> if necessary.
+
Make the zfs folder in 'etc' and copy your zpool.cache
 +
# ##i##mkdir etc/zfs
 +
# ##i##cp /etc/zfs/zpool.cache etc/zfs
 +
 
 +
Chroot into Funtoo
 +
# ##i##env -i HOME=/root TERM=$TERM chroot . bash -l
 +
</console>
 +
 
 +
=== In Chroot ===
 +
 
 +
<console>
 +
Create a symbolic link to your mountpoints
 +
# ##i##ln -sf /proc/mounts /etc/mtab
 +
 
 +
Sync your tree
 +
# ##i##emerge --sync
 +
</console>
 +
 
 +
=== Add filesystems to /etc/fstab ===
 +
 
 +
Before we continue to compile and or install our kernel in the next step, we will edit the <tt>/etc/fstab</tt> file because if we decide to install our kernel through portage, portage will need to know where our <tt>/boot</tt> is, so that it can place the files in there.
 +
 
 +
Edit <tt>/etc/fstab</tt>:
 +
 
 +
<pre>
 +
# <fs>                  <mountpoint>    <type>          <opts>          <dump/pass>
 +
 
 +
/dev/sda1              /boot          ext2            defaults        0 2
 +
/dev/zvol/tank/swap    none            swap            sw              0 0
 +
</pre>
 +
 
 +
== Kernel Configuration ==
 +
To speed up this step, you can install a pre-configured/compiled kernel called '''bliss-kernel'''. This kernel already has the correct configurations for ZFS and a variety of other scenarios. It's a vanilla kernel from kernel.org without any external patches.
 +
 
 +
To install {{Package|sys-kernel/bliss-kernel}} type the following:
 +
 
 +
<console>
 +
# ##i##emerge bliss-kernel
 +
</console>
 +
 
 +
Now make sure that your <tt>/usr/src/linux symlink</tt> is pointing to this kernel by typing the following:
 +
 
 +
<console>
 +
# ##i##eselect kernel list
 +
Available kernel symlink targets:
 +
[1]  linux-3.12.13-KS.02 *
 +
</console>
 +
 
 +
You should see a star next to the version you installed. In this case it was 3.12.13-KS.02. If it's not set, you can type '''eselect kernel set #'''.
 +
 
 +
== Installing the ZFS userspace tools and kernel modules ==
 +
Emerge {{Package|sys-fs/zfs}}. This package will bring in {{Package|sys-kernel/spl}}, and {{Package|sys-fs/zfs-kmod}} as its dependencies:
 +
 
 +
<console>
 +
# ##i##emerge zfs
 +
</console>
 +
 
 +
Check to make sure that the zfs tools are working. The <code>zpool.cache</code> file that you copied before should be displayed.
 +
 
 +
<console>
 +
# ##i##zpool status
 +
# ##i##zfs list
 +
</console>
 +
 
 +
If everything worked, continue.
 +
 
 +
== Installing & Configuring the Bootloader ==
 +
 
 +
For the bootloader and its configuration we will use '''bliss-boot'''. This is a new program that is designed to generate a simple, human-readable/editable, configuration file for a variety of bootloaders. It currently supports grub2, extlinux, and lilo.
 +
 
 +
Depending which bootloader you want ('''grub2''', '''extlinux''', '''lilo'''), add a use flag for it and emerge bliss-boot:
 +
 
 +
<console>
 +
# ##i##echo "sys-boot/bliss-boot grub2" >> /etc/portage/package.use
 +
# ##i##emerge bliss-boot
 +
</console>
 +
 
 +
=== GRUB 2 ===
 +
If you enabled the '''grub2''' flag in '''bliss-boot''', then grub has now been installed.
 +
You can check that grub is version 2.00 by doing the following command:
 +
 
 +
<console>
 +
# ##i##grub-install --version
 +
grub-install (GRUB) 2.00
 +
</console>
 +
 
 +
Now install grub to the drive itself (not a partition):
 +
<console>
 +
# ##i##grub-install /dev/sda
 +
</console>
 +
 
 +
You should receive the following message:
 +
 
 +
<console>
 +
Installation finished. No error reported.
 +
</console>
 +
 
 +
You should now see some a grub directory with some files inside your /boot folder:
 +
 
 +
<console>
 +
# ##i##ls -l /boot/grub
 +
total 2520
 +
-rw-r--r-- 1 root root    1024 Jan  4 16:09 grubenv
 +
drwxr-xr-x 2 root root    8192 Jan 12 14:29 i386-pc
 +
drwxr-xr-x 2 root root    4096 Jan 12 14:28 locale
 +
-rw-r--r-- 1 root root 2555597 Feb  4 11:50 unifont.pf2
 +
</console>
 +
 
 +
==== Configuring GRUB 2 ====
 +
In order to generate our grub2.cfg file, we will first configure bliss-boot so that it knows what we want.
 +
The 'bliss-boot' configuration file is located in '''/etc/bliss-boot/conf.py'''. Open that file and make sure that the following variables are set appropriately:
 +
 
 +
<pre>
 +
# This should be set to the bootloader you installed earlier
 +
bootloader = "grub2"
 +
 
 +
# This should be set to the kernel you installed earlier
 +
default = "3.12.13-KS.02"
 +
</pre>
 +
 
 +
Scroll all the way down until you find 'kernels'. You will need to add the kernels and the options
 +
you want for these kernels here. Below are a few configuration options depending if you are using
 +
'''bliss-initramfs''' or '''genkernel'''.
 +
 
 +
===== Bliss Initramfs Creator =====
 +
<pre>
 +
kernel = {
 +
    '3.12.13-KS.02' : 'root=tank/funtoo/root quiet',
 +
}
 +
</pre>
 +
 
 +
'''If you are using encryption then you would let the initramfs know:'''
 +
 
 +
#"What type of encryption authentication you want to use? ('''enc_type=''')
 +
::* pass = will ask for passphrase directly
 +
::* key = a plain unencrypted key file
 +
::* key_gpg = an encrypted key file
 +
#"Where is the encrypted drive?" ('''enc_root=''')
 +
#"Where is the root pool after it has been decrypted?" ('''root=''')
 +
 
 +
<pre>
 +
kernel = {
 +
    '3.12.13-KS.02' : 'root=tank/funtoo/root enc_root=/dev/sda3 enc_type=pass quiet',
 +
}
 +
</pre>
 +
 
 +
===== genkernel =====
 +
<pre>
 +
kernel = {
 +
    '3.12.13-KS.02' : 'real_root=ZFS=tank/funtoo/root dozfs=force quiet',
 +
}
 +
</pre>
 +
 
 +
'''If you are using encryption you can add the crypt_root option:'''
 +
 
 +
<pre>
 +
kernel = {
 +
    '3.12.13-KS.02' : 'real_root=ZFS=tank/funtoo/root dozfs=force crypt_root=/dev/sda3 quiet',
 +
}
 +
</pre>
 +
 
 +
 
 +
=== LILO ===
 +
If you enabled the '''lilo''' flag in '''bliss-boot''', then lilo has now been installed.
 +
 
 +
We first need to generate a '''lilo.conf''' file before we can install this bootloader.
 +
 
 +
 
 +
<pre>
 +
boot=/dev/sda
 +
prompt
 +
timeout=4
 +
default=Funtoo
 +
 
 +
image=/boot/bzImage
 +
      label=Funtoo
 +
      read-only
 +
      append="root=tank/os/funtoo/root"
 +
      initrd=/boot/initramfs
 +
</pre>
 +
All that is left now is to install the bootcode to the MBR.
 +
 
 +
This can be accomplished by running:
 +
<console># ##i##/sbin/lilo</console>
 +
If it is successful you should see:
 +
<console>
 +
Warning: LBA32 addressing assumed
 +
Added Funtoo + *
 +
One warning was issued
 +
</console>
 +
 
 +
== Create the initramfs ==
 +
There are two ways to do this, you can use genkernel, or you can use my bliss initramfs creator. I will show you both.
 +
 
 +
=== genkernel ===
 +
<console>
 +
# ##i##emerge sys-kernel/genkernel
 +
# You only need to add --luks if you used encryption
 +
# ##i##genkernel --zfs --luks initramfs
 +
</console>
 +
 
 +
=== Bliss Initramfs Creator ===
 +
If you are encrypting your drives, then add the "luks" use flag to your package.use before emerging:
 +
 
 +
<console>
 +
# ##i##echo "sys-kernel/bliss-initramfs luks" >> /etc/portage/package.use
 +
</console>
 +
 
 +
Now install the creator:
 +
 
 +
<console>
 +
# ##i##emerge bliss-initramfs
 +
</console>
 +
 
 +
 
 +
Then go into the install directory, run the script as root, and place it into /boot:
 +
<console># ##i##cd /opt/bliss-initramfs
 +
# ##i##./createInit
 +
# ##i##mv initrd-<kernel_name> /boot
 +
</console>
 +
'''<kernel_name>''' is the name of what you selected in the initramfs creator, and the name of the outputted file.
 +
 
 +
== Final configuration ==
 +
=== Add the zfs tools to openrc ===
 +
<console># ##i##rc-update add zfs boot</console>
 +
 
 +
=== Clean up and reboot ===
 +
We are almost done, we are just going to clean up, '''set our root password''', and unmount whatever we mounted and get out.
 +
 
 +
<console>
 +
Delete the stage3 tarball that you downloaded earlier so it doesn't take up space.
 +
# ##i##cd /
 +
# ##i##rm stage3-latest.tar.xz
 +
 
 +
Set your root password
 +
# ##i##passwd
 +
>> Enter your password, you won't see what you are writing (for security reasons), but it is there!
 +
 
 +
Get out of the chroot environment
 +
# ##i##exit
 +
 
 +
Unmount all the kernel filesystem stuff and boot (if you have a separate /boot)
 +
# ##i##umount -l proc dev sys boot
 +
 
 +
Turn off the swap
 +
# ##i##swapoff /dev/zvol/tank/swap
 +
 
 +
Export the zpool
 +
# ##i##cd /
 +
# ##i##zpool export tank
 +
 
 +
Reboot
 +
# ##i##reboot
 +
</console>
 +
 
 +
{{fancyimportant|'''Don't forget to set your root password as stated above before exiting chroot and rebooting. If you don't set the root password, you won't be able to log into your new system.'''}}
 +
 
 +
and that should be enough to get your system to boot on ZFS.
 +
 
 +
== After reboot ==
 +
=== Create initial ZFS Snapshot ===
 +
Continue to set up anything you need in terms of /etc configurations. Once you have everything the way you like it, take a snapshot of your system. You will be using this snapshot to revert back to this state if anything ever happens to your system down the road. The snapshots are cheap, and almost instant.
 +
 
 +
To take the snapshot of your system, type the following:
 +
<console># ##i##zfs snapshot -r tank@install</console>
 +
 
 +
To see if your snapshot was taken, type:
 +
<console># ##i##zfs list -t snapshot</console>
 +
 
 +
If your machine ever fails and you need to get back to this state, just type (This will only revert your / dataset while keeping the rest of your data intact):
 +
<console># ##i##zfs rollback tank/os/funtoo/root@install</console>
 +
 
 +
{{fancyimportant|'''For a detailed overview, presentation of ZFS' capabilities, as well as usage examples, please refer to the [[ZFS_Fun|ZFS Fun]] page.'''}}
  
 
[[Category:HOWTO]]
 
[[Category:HOWTO]]
[[Category:Tutorial]]
+
[[Category:Filesystems]]
 +
[[Category:Featured]]
 +
 
 +
__NOTITLE__

Revision as of 21:20, 4 March 2014

Contents

Introduction

This tutorial will show you how to install Funtoo on ZFS (rootfs). This tutorial is meant to be an "overlay" over the Regular Funtoo Installation. Follow the normal installation and only use this guide for steps 2, 3, and 8.

Introduction to ZFS

Since ZFS is a new technology for Linux, it can be helpful to understand some of its benefits, particularly in comparison to BTRFS, another popular next-generation Linux filesystem:

  • On Linux, the ZFS code can be updated independently of the kernel to obtain the latest fixes. btrfs is exclusive to Linux and you need to build the latest kernel sources to get the latest fixes.
  • ZFS is supported on multiple platforms. The platforms with the best support are Solaris, FreeBSD and Linux. Other platforms with varying degrees of support are NetBSD, Mac OS X and Windows. btrfs is exclusive to Linux.
  • ZFS has the Adaptive Replacement Cache replacement algorithm while btrfs uses the Linux kernel's Last Recently Used replacement algorithm. The former often has an overwhelmingly superior hit rate, which means fewer disk accesses.
  • ZFS has the ZFS Intent Log and SLOG devices, which accelerates small synchronous write performance.
  • ZFS handles internal fragmentation gracefully, such that you can fill it until 100%. Internal fragmentation in btrfs can make btrfs think it is full at 10%. Btrfs has no automatic rebalancing code, so it requires a manual rebalance to correct it.
  • ZFS has raidz, which is like RAID 5/6 (or a hypothetical RAID 7 that supports 3 parity disks), except it does not suffer from the RAID write hole issue thanks to its use of CoW and a variable stripe size. btrfs gained integrated RAID 5/6 functionality in Linux 3.9. However, its implementation uses a stripe cache that can only partially mitigate the effect of the RAID write hole.
  • ZFS send/receive implementation supports incremental update when doing backups. btrfs' send/receive implementation requires sending the entire snapshot.
  • ZFS supports data deduplication, which is a memory hog and only works well for specialized workloads. btrfs has no equivalent.
  • ZFS datasets have a hierarchical namespace while btrfs subvolumes have a flat namespace.
  • ZFS has the ability to create virtual block devices called zvols in its namespace. btrfs has no equivalent and must rely on the loop device for this functionality, which is cumbersome.

The only area where btrfs is ahead of ZFS is in the area of small file efficiency. btrfs supports a feature called block suballocation, which enables it to store small files far more efficiently than ZFS. It is possible to use another filesystem (e.g. reiserfs) on top of a ZFS zvol to obtain similar benefits (with arguably better data integrity) when dealing with many small files (e.g. the portage tree).

Disclaimers

Warning: This guide is a work in progress. Expect some quirks.
Important: Since ZFS was really designed for 64 bit systems, we are only recommending and supporting 64 bit platforms and installations. We will not be supporting 32 bit platforms!

Video Tutorial

As a companion to the installation instructions below, a YouTube video tutorial is now available:

Important: The video and guide are currently out of sync. The video has newer instructions. The guide needs to be updated.

Downloading the ISO (With ZFS)

In order for us to install Funtoo on ZFS, you will need an environment that already provides the ZFS tools. Therefore we will download a customized version of System Rescue CD with ZFS included.

Name: sysresccd-4.0.1_zfs_0.6.2.iso  (545 MB)
Release Date: 2014-02-25
md5sum 01f4e6929247d54db77ab7be4d156d85


Download System Rescue CD with ZFS

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:

Make a temporary directory
# mkdir /tmp/loop

Mount the iso
# mount -o ro,loop /root/sysresccd-4.0.1_zfs_0.6.2.iso /tmp/loop

Run the usb installer
# /tmp/loop/usb_inst.sh

That should be all you need to do to get your flash drive working.

Booting the ISO

Warning: When booting into the ISO, Make sure that you select the "Alternate 64 bit kernel (altker64)". The ZFS modules have been built specifically for this kernel rather than the standard kernel. If you select a different kernel, you will get a fail to load module stack error message.

Creating partitions

There are two ways to partition your disk: You can use your entire drive and let ZFS automatically partition it for you, or you can do it manually.

We will be showing you how to partition it manually because if you partition it manually you get to create your own layout, you get to have your own separate /boot partition (Which is nice since not every bootloader supports booting from ZFS pools), and you get to boot into RAID10, RAID5 (RAIDZ) pools and any other layouts due to you having a separate /boot partition.

gdisk (GPT Style)

A Fresh Start:

First lets make sure that the disk is completely wiped from any previous disk labels and partitions. We will also assume that /dev/sda is the target drive.

# sgdisk -Z /dev/sda
Warning: This is a destructive operation and the program will not ask you for confirmation! Make sure you really don't want anything on this disk.

Now that we have a clean drive, we will create the new layout.

First open up the application:

# gdisk /dev/sda

Create Partition 1 (boot):

Command: n ↵
Partition Number: 
First sector: 
Last sector: +250M ↵
Hex Code: 

Create Partition 2 (BIOS Boot Partition):

Command: n ↵
Partition Number: 
First sector: 
Last sector: +32M ↵
Hex Code: EF02 ↵

Create Partition 3 (ZFS):

Command: n ↵
Partition Number: 
First sector: 
Last sector: 
Hex Code: bf00 ↵

Command: p ↵

Number  Start (sector)    End (sector)  Size       Code  Name
   1            2048          514047   250.0 MiB   8300  Linux filesystem
   2          514048          579583   32.0 MiB    EF02  BIOS boot partition
   3          579584      1953525134   931.2 GiB   BF00  Solaris root

Command: w ↵


Format your /boot partition

# mkfs.ext2 -m 1 /dev/sda1

Encryption (Optional)

If you want encryption, then create your encrypted vault(s) now by doing the following:

# cryptsetup luksFormat /dev/sda3
# cryptsetup luksOpen /dev/sda3 vault_1
Warning: On some machines, a combination of ZFS and LUKS has caused instability and system crashes.

Create the zpool

We will first create the pool. The pool will be named `tank` and the disk will be aligned to 4096 (using ashift=12)

# zpool create -f -o ashift=12 -o cachefile= -O compression=on -m none -R /mnt/funtoo tank /dev/sda3
Important: If you are using encrypted root, change /dev/sda3 to /dev/mapper/vault_1.
Note: If you have a previous pool that you would like to import, you can do a: zpool import -f -R /mnt/funtoo <pool_name>.

Create the zfs datasets

We will now create some datasets. For this installation, we will create a small but future proof amount of datasets. We will have a dataset for the OS (/), and your swap. We will also show you how to create some optional datasets: /home, /var, /usr/src, and /usr/portage.

Create some empty containers for organization purposes, and make the dataset that will hold /
# zfs create -p tank/funtoo
# zfs create -o mountpoint=/ tank/funtoo/root

Optional, but recommended datasets: /home
# zfs create -o mountpoint=/home tank/funtoo/home

Optional datasets: /usr/src, /usr/portage/{distfiles,packages}
# zfs create -o mountpoint=/usr/src tank/funtoo/src
# zfs create -o mountpoint=/usr/portage -o compression=off tank/funtoo/portage
# zfs create -o mountpoint=/usr/portage/distfiles tank/funtoo/portage/distfiles
# zfs create -o mountpoint=/usr/portage/packages tank/funtoo/portage/packages

Create your swap zvol

For modern machines that have greater than 4 GB of RAM, A swap size of 2G should be enough. However if your machine doesn't have a lot of RAM, the rule of thumb is either 2x the RAM or RAM + 1 GB.

For this tutorial we will assume that it is a newer machine and make a 2 GB swap.

# zfs create -o sync=always -o primarycache=metadata -o secondarycache=none -o volblocksize=4K -V 2G tank/swap

Format your swap zvol

# mkswap -f /dev/zvol/tank/swap
# swapon /dev/zvol/tank/swap

Now we will continue to install funtoo.

Installing Funtoo

Pre-Chroot

Go into the directory that you will chroot into
# cd /mnt/funtoo

Make a boot folder and mount your boot drive
# mkdir boot
# mount /dev/sda1 boot

Now download and extract the Funtoo stage3 ...

Once you've extracted the stage3, do a few more preparations and chroot into your new funtoo environment:

Bind the kernel related directories
# mount -t proc none proc
# mount --rbind /dev dev
# mount --rbind /sys sys

Copy network settings
# cp -f /etc/resolv.conf etc

Make the zfs folder in 'etc' and copy your zpool.cache
# mkdir etc/zfs
# cp /etc/zfs/zpool.cache etc/zfs

Chroot into Funtoo
# env -i HOME=/root TERM=$TERM chroot . bash -l

In Chroot

Create a symbolic link to your mountpoints
# ln -sf /proc/mounts /etc/mtab

Sync your tree
# emerge --sync

Add filesystems to /etc/fstab

Before we continue to compile and or install our kernel in the next step, we will edit the /etc/fstab file because if we decide to install our kernel through portage, portage will need to know where our /boot is, so that it can place the files in there.

Edit /etc/fstab:

# <fs>                  <mountpoint>    <type>          <opts>          <dump/pass>

/dev/sda1               /boot           ext2            defaults        0 2
/dev/zvol/tank/swap     none            swap            sw              0 0

Kernel Configuration

To speed up this step, you can install a pre-configured/compiled kernel called bliss-kernel. This kernel already has the correct configurations for ZFS and a variety of other scenarios. It's a vanilla kernel from kernel.org without any external patches.

To install sys-kernel/bliss-kernel type the following:

# emerge bliss-kernel

Now make sure that your /usr/src/linux symlink is pointing to this kernel by typing the following:

# eselect kernel list
Available kernel symlink targets:
[1]   linux-3.12.13-KS.02 *

You should see a star next to the version you installed. In this case it was 3.12.13-KS.02. If it's not set, you can type eselect kernel set #.

Installing the ZFS userspace tools and kernel modules

Emerge sys-fs/zfs. This package will bring in sys-kernel/spl, and sys-fs/zfs-kmod as its dependencies:

# emerge zfs

Check to make sure that the zfs tools are working. The zpool.cache file that you copied before should be displayed.

# zpool status
# zfs list

If everything worked, continue.

Installing & Configuring the Bootloader

For the bootloader and its configuration we will use bliss-boot. This is a new program that is designed to generate a simple, human-readable/editable, configuration file for a variety of bootloaders. It currently supports grub2, extlinux, and lilo.

Depending which bootloader you want (grub2, extlinux, lilo), add a use flag for it and emerge bliss-boot:

# echo "sys-boot/bliss-boot grub2" >> /etc/portage/package.use
# emerge bliss-boot

GRUB 2

If you enabled the grub2 flag in bliss-boot, then grub has now been installed. You can check that grub is version 2.00 by doing the following command:

# grub-install --version
grub-install (GRUB) 2.00

Now install grub to the drive itself (not a partition):

# grub-install /dev/sda

You should receive the following message:

Installation finished. No error reported.

You should now see some a grub directory with some files inside your /boot folder:

# ls -l /boot/grub
total 2520
-rw-r--r-- 1 root root    1024 Jan  4 16:09 grubenv
drwxr-xr-x 2 root root    8192 Jan 12 14:29 i386-pc
drwxr-xr-x 2 root root    4096 Jan 12 14:28 locale
-rw-r--r-- 1 root root 2555597 Feb  4 11:50 unifont.pf2

Configuring GRUB 2

In order to generate our grub2.cfg file, we will first configure bliss-boot so that it knows what we want. The 'bliss-boot' configuration file is located in /etc/bliss-boot/conf.py. Open that file and make sure that the following variables are set appropriately:

# This should be set to the bootloader you installed earlier
bootloader = "grub2"

# This should be set to the kernel you installed earlier
default = "3.12.13-KS.02" 

Scroll all the way down until you find 'kernels'. You will need to add the kernels and the options you want for these kernels here. Below are a few configuration options depending if you are using bliss-initramfs or genkernel.

Bliss Initramfs Creator
kernel = {
    '3.12.13-KS.02' : 'root=tank/funtoo/root quiet',
}

If you are using encryption then you would let the initramfs know:

  1. "What type of encryption authentication you want to use? (enc_type=)
  • pass = will ask for passphrase directly
  • key = a plain unencrypted key file
  • key_gpg = an encrypted key file
  1. "Where is the encrypted drive?" (enc_root=)
  2. "Where is the root pool after it has been decrypted?" (root=)
kernel = {
    '3.12.13-KS.02' : 'root=tank/funtoo/root enc_root=/dev/sda3 enc_type=pass quiet',
}
genkernel
kernel = {
    '3.12.13-KS.02' : 'real_root=ZFS=tank/funtoo/root dozfs=force quiet',
}

If you are using encryption you can add the crypt_root option:

kernel = {
    '3.12.13-KS.02' : 'real_root=ZFS=tank/funtoo/root dozfs=force crypt_root=/dev/sda3 quiet',
}


LILO

If you enabled the lilo flag in bliss-boot, then lilo has now been installed.

We first need to generate a lilo.conf file before we can install this bootloader.


boot=/dev/sda
prompt
timeout=4
default=Funtoo

image=/boot/bzImage
      label=Funtoo
      read-only
      append="root=tank/os/funtoo/root"
      initrd=/boot/initramfs

All that is left now is to install the bootcode to the MBR.

This can be accomplished by running:

# /sbin/lilo

If it is successful you should see:

Warning: LBA32 addressing assumed
Added Funtoo + *
One warning was issued

Create the initramfs

There are two ways to do this, you can use genkernel, or you can use my bliss initramfs creator. I will show you both.

genkernel

# emerge sys-kernel/genkernel
# You only need to add --luks if you used encryption
# genkernel --zfs --luks initramfs

Bliss Initramfs Creator

If you are encrypting your drives, then add the "luks" use flag to your package.use before emerging:

# echo "sys-kernel/bliss-initramfs luks" >> /etc/portage/package.use

Now install the creator:

# emerge bliss-initramfs


Then go into the install directory, run the script as root, and place it into /boot:

# cd /opt/bliss-initramfs
# ./createInit
# mv initrd-<kernel_name> /boot

<kernel_name> is the name of what you selected in the initramfs creator, and the name of the outputted file.

Final configuration

Add the zfs tools to openrc

# rc-update add zfs boot

Clean up and reboot

We are almost done, we are just going to clean up, set our root password, and unmount whatever we mounted and get out.

Delete the stage3 tarball that you downloaded earlier so it doesn't take up space.
# cd /
# rm stage3-latest.tar.xz

Set your root password
# passwd
>> Enter your password, you won't see what you are writing (for security reasons), but it is there!

Get out of the chroot environment
# exit

Unmount all the kernel filesystem stuff and boot (if you have a separate /boot)
# umount -l proc dev sys boot

Turn off the swap
# swapoff /dev/zvol/tank/swap

Export the zpool
# cd /
# zpool export tank

Reboot
# reboot
Important: Don't forget to set your root password as stated above before exiting chroot and rebooting. If you don't set the root password, you won't be able to log into your new system.

and that should be enough to get your system to boot on ZFS.

After reboot

Create initial ZFS Snapshot

Continue to set up anything you need in terms of /etc configurations. Once you have everything the way you like it, take a snapshot of your system. You will be using this snapshot to revert back to this state if anything ever happens to your system down the road. The snapshots are cheap, and almost instant.

To take the snapshot of your system, type the following:

# zfs snapshot -r tank@install

To see if your snapshot was taken, type:

# zfs list -t snapshot

If your machine ever fails and you need to get back to this state, just type (This will only revert your / dataset while keeping the rest of your data intact):

# zfs rollback tank/os/funtoo/root@install
Important: For a detailed overview, presentation of ZFS' capabilities, as well as usage examples, please refer to the ZFS Fun page.