It has come to my attention that many people consider installing Gentoo, and in effect, Funtoo, a hard task to complete. Some people have also shown interest in my particular setup. In addition, my favourite English teacher, Anne the Lion, has tasked us students to write a tutorial to assess our English skills.
As such, I have written this tutorial to show people my installation steps, and mentally please my teacher. If you have any suggestions or criticism, please find me on IRC. The networks I frequent and the nickname I use can be found on my homepage.
This tutorial assumes a few things from you. If you do not meet most of these assumptions, this guide is probably not for you. You can of course still read it, however, there might be a lot of jargon you do not understand, making the tutorial more complex to understand.
- You have experience with GNU+Linux
- You know your way in the terminal
- You are not afraid of using text-based applications
- You have experience reading through manuals and documentation
- You are not afraid to spend some hours on IRC to help you troubleshoot issues
This tutorial will guide you through a not-so-basic installation of the Funtoo GNU+Linux distribution. It is based on one of my own installations, but slightly simplified.
The live environment
Before you can get started with setting up the system, you will need something to set it up with. We will be using a live environment for this purpose. My personal choice for this task is the Gentoo-based SystemRescueCD.
You can use any other live environment your prefer, however, this tutorial will only guide you into preparing the System Rescue CD.
Getting the live USB image
You can download the System Rescue CD at one of the following locations:
Setting up the live USB
After downloading the image, mount it somewhere:
Once it is mounted, you can run the installer bundled with the image by running
Select the right device and wait for the installer to finish up.
Booting the USB
To begin using the live environment so you can install something with it, boot it up. Make sure the USB is in the machine, and reboot it. Enter the BIOS/UEFI settings and make sure to either make the USB device a higher boot priority, or select it to be the boot device for one boot. The availability and location of these options differs per machine, so be sure to check the manual or look around online for instructions if it is not clear to you.
The hardware you are installing on needs to be prepared. This could mean manually configuring your hardware RAID if you use this and configuring other exotic setups. This tutorial will not go into details for such setups, as there is a near infinite amount of possible options. Instead, you should stick to simply configuring your storage device.
The size of your storage device should be at least 35GB to be safe and have some space for personal data. The partitioning layout this guide is aiming for is the following:
If you already an advanced user, you are of course free to diverge from the guide here.
Partition the drive
The first part is to setup partitions. This can be done by calling
Let us wipe the entire disk and start with a clean slate. You can do this by
o and pressing enter. When asked wether you are sure, type
Now you are going to create two partitions, one for
/boot and one for
lvm. Following is a list of what to enter.
pressing the enter key.
Setting up encryption
Any system should be safe. Encryption is just a small part, but in my opinion
very important. We are going to encrypt the entire
lvm partition using
luks. The frontend tool to be used for this is
cryptsetup will ask you for a passphrase. Make sure to use a good one,
preferably at least 20 characters in length.
Once the partition has been encrypted, open the device so it can be used by
cryptsetup luksOpen /dev/sda2 dmcrypt_lvm.
Set up LVM
Once the encrypted partition has been unlocked, you can setup
lvm on it. To
initialize an lvm volume on this partition, run the following:
The lvm volume has now been prepared, and you can start adding volumes to it to be used as partitions. It is recommended to have a swap partition as well. The size of this partition depends on the amount of RAM you have available. Due to my availability to big disks, I generally opt for a swap partition the same size as my total RAM in the machine. To make the tutorial work for this as well, a subshell is called to figure out the size of the swap partition.
Now you are ready to create usable filesystems on the partitions:
If you're thinking at this point "where's my home partition?", it's not initialized here. ZFS requires custom kernel modules which will be built later, after the initial kernel has been compiled.
Mount the filesystems
Next up is mounting all filesystems so you can install files to them. First, you mount the root filesystem:
Now you can add some directories for the other mountpoints. This can be done in
Next you can mount all other mountpoints on the new directories:
Let's also enable swap and ramdisks for the temporary storage directories:
Now that all mountpoints have been set up, installation of the actual OS can begin. This is done by downloading a "stage 3" tarball containing a bare minimal Funtoo installation and extracting it with the right options.
The stage 3 tarball can be downloaded from build.funtoo.org. It is easiest to download and extract the tarball in the root filesystem, so let's do that:
Once extraction is complete, you can opt to delete the tarball as it is no
longer needed at this point. You can delete it by invoking
You now have a bare Funtoo installation ready on your machine. But before you can actually use it, you should do some configuration.
Before you get to the configuration part, you should
into the system. This allows you to enter your new Funtoo installation before it
can properly boot. If your system ever breaks and you are unable to boot into it
anymore, you can redo the mounting section of this guide and this chrooting
section to get into it and resolve your issues.
The chrooting requires a couple extra mounts, so the chroot can interface with the hardware provided by the system above it:
Once these mountpoints are set, you will need to copy over
resolv.conf so the
chroot can resolve DNS names:
Now that everything is prepared in the chroot, you can enter your Funtoo installation using the following:
Set up the portage tree
The portage tree is a collection of files which are used by the package manager to find out which software it can install, and more importantly, how to install it.
The default location in Funtoo for your portage tree is in
However, as I use multiple sources for my portage tree, I prefer to set it up
/usr/portage/funtoo. This is not a required step, but advised nonetheless.
In order to change this, open up
/etc/portage/repos.conf/gentoo in your
favourite editor. Funtoo comes with
ed by default.
recommended as the standard editor. After opening the file, change the
location key to point to
When you have modified
/etc/portage/repos.conf/gentoo (or not, if you do not
want to change this default), continue to download your first version of the
Everytime you want to update your system, you will have to do an
to update the portage tree first. It is managed by
can bring some side effects. The most notable one is that the tree will grow
over time with old commit data. If you wish to clean this up, simply
rm -rf /usr/portage/* && emerge --sync to regenerate it from scratch
Setting up your system settings
In order to make the system work properly, some setup has to be performed. This will involve editing some text files, for which you can use your favourite editor again.
We will begin with the most important one,
/etc/fstab. This file holds
information on your mountpoints. Some of the mountpoints are best configured
with UUIDs, because the device enumeration can sometimes differ. If you have
multiple storage devices in your system, this could as well be a hard
requirement. UUIDs are unique to each storage device, so you will have to figure
out your UUIDs yourself. You can do this by running
lsblk -o +UUID. Take note
of the UUID of your boot device.
Once you know the UUID, open up
/etc/fstab with whatever editor you feel
comfortable with and make it look like the following block of text. Do not
forget to update the UUIDs!
The localtime comes next. This is to make sure your time is set correctly. An
incorrect time can cause issues such as secure connections failing. To set your
localtime, all you need to do is create a symlink. The file you need to symlink
to is stored in
/usr/share/zoneinfo. The files are sorted by continent. As
someone who lives in the Netherlands, I'd use
It is important to also correctly set your hardware clock, in case it is off.
Check if your time and date are correct by invoking
date. If these settings
are correct, you can skip towards the next heading. Otherwise, keep on reading
To set the correct time, you can use the
date utility again. When invoked with
an argument in the form of
MMDDhhmmYYYY, it will set the date and time instead
of check it. The following command would set the date to the first of October
2016, and the time to 17:29:
After you correctly set the date and time to whatever it currently is, sync it to the hardware clock so it is correct across reboots:
Another important part to configure is the
make.conf file. This file contains
settings for portage and some options for compilers. This file can also be made
a directory. This way, you can split off your configs into multiple files for
easier maintainance. The files will be loaded alphabetically. The way you set it
up is completely up to you, though I would recommend removing the default
/etc/portage/make.conf and making it a directory instead.
Once you have decided how to setup your make.conf, it is time to add some data in the file(s). Following is a list of useful variables to set up, with a block containing my own settings for it. You can copy these for yourself, or dig aroudn some manpages to find out what you exactly want yourself.
USE holds global USE flags. These are used to configure your packages. You can
turn features on and off using these, and the ebuilds will configure the
packages to enable or disable these features.
FEATURES variable allows enabling of various portage features. Mine are
setup to drop privileges so root is used as little as possible and to do as much
parallel as possible to speed up the process. Additionally, I use the
feature to build binary packages for use on other systems. This can save you a
great deal of time if you have multiple systems running Funtoo.
EMERGE_DEFAULT_OPTS can be used to add some flags to every emerge you invoke.
This way you can force emerge to always ask for confirmation.
CXXFLAGS variables hold compiler-specific options. It is
very important to not use newlines in these two, as they will break
cmake. Other than that, it is just a regular shell variable like
This variable is not as important as the others. You can even opt to leave it
out completely. If, however, you wish to limit portage to only install free
software (free as in freedom, not gratis), you can set it to the same value as
me. Do note that if you use this, you will need to setup the
/etc/portage/package.license as well.
MAKEOPTS are the arguments passed to
make. This can be used to instruct
make to use multiple threads when compiling software. The amount of threads
can be set with the
-j flag. The general rule of thumb for this is to use
$(($(nproc) + 1)).
DISTDIR variables set the location to store binary packages
after building, and the location to store distfiles. In order to use the
/var/packages partitions, these must be set.
package.mask can be made a directory containing
package.mask file(s) allow you to "mask" packages, instructing portage to
ignore these. It can also let you mask certain versions of packages. This way
you can skip a broken version or stick to a certain version for whatever reason.
Since this tutorial uses ZFS, there is such a reason to do exactly that.
ZFS requires a Linux at version 4.4 or lower. The latest kernel is much higher than that, so it is necessary to mask newer kernel versions. This is a single line of configuration, and as such can be done without a fancy editor. Simply invoke the following magic:
This file can be setup as a directory too, just like
package.mask. Using this file or directory you can add per-package license
exceptions. This is therefore only needed if you setup a strict license limit.
The kernel comes with some sources under the
freedist license, which is not
@FREE. As such, if you want to install kernel sources you will have to
make an exception for this license on this package.
As one of the last files to setup, the hostname should be set in
hostname variable in this file should be set to
the hostname of the machine. You can pick any name you like, but should be
unique across your network.
Preparing your first kernel
Every system needs a kernel, a piece of software to interface with the hardware. Funtoo, like every GNU+Linux distribution, uses the Linux kernel for this task.
For this task, you will first need to decide on a source set to use. All source
sets share the same base, but they have different patches applied. It is
recommended to use
sys-kernel/gentoo-sources. If this isn't bleeding edge
enough, you can use
sys-kernel/git-sources instead. If you just want the
latest official kernel without the gentoo patchset, pick
sys-kernel/vanilla-sources. No matter which source set you use, the
compilation and installation process remains the same.
Install whichever source set you want to use, this guide will use
sys-kernel/gentoo-sources. In order to save some yes-pressing later on, the
emerge command here will install some additional packages which are needed for
the system to function properly.
genkernel command will run the kernel menuconfig utility. If you have
exotic hardware that needs special support, this is the place to enable it. The
defaults are sane for most systems. If you have nothing to configure here, just
exit the menuconfig and let
genkernel build a custom kernel and initramfs for
you. As the guide uses LVM and LUKS, you will need to have support for these
things in your kernel. You will need to enable the following options at the
The kernel is now installed at
/boot, and all the required parts to build
custom kernel modules are available. This means it is now possible to build the
First install the kernel module here. Since the live kernel does not have the zfs modules from the chroot, you must create the pool and the volumes after the first reboot.
Once it has been compiled, you can add the ZFS services to start up by default. This will load the kernel module for you and all additional services that make ZFS perform its job well.
Installing a bootloader
Before building your kernel,
boot-update was installed. This pulls in
grub, the recommended bootloader for Funtoo. It doesn't
require a lot of configuration thanks to the
boot-update script, which will
grub for you.
Before running the script, there's one place to update as this setup uses
/etc/boot.conf in your favourite editor and let the file display
something like this:
boot-update is configured, install
grub as an UEFI bootloader and
generate the configs for it using
boot-update. You should make sure the
grub directory exists in
/boot as well.
Set your system profile
Your system is now ready to boot and use. However, some things are still not configured. These can in some cases be configured after rebooting, but it is recommended to fix it all up now. The first part is setting your system profile.
For a full list of settings, check
epro list. Maybe you want to use this
system as something other than a workstation, or want to enable the
To get the same profile settings as I use for my work environments, run the following:
Running the first full system update
The stage 3 tarball may have been the latest, but it might still have some
slightly outdated packages. In addition, now that your system profile is set up,
some applications may be configured to have different feature sets enabled. To
make sure everything is in the best possible state, it is recommended to run a
full system update now. Since some of our options are already set as
EMERGE_DEFAULT_OPTS, this is as simple as
Installing supporting software
This is software you will more than likely need on any standard system. If you're an advanced user you can decide to skip this and make your own choices, otherwise it is recommended to install this software as well.
Configuring supporting software
Some of the supporting software has to be turned on explicitly or have a configuration file tweaked. If you opted to not use a given recommended package, you can skip the section with the same name.
connman is a simple connection manager. It's
lightweight, fast and does its job pretty well. To enable this service at boot,
If you want to setup wireless connection authentication credentials, read up on
sudo utility allows certain users, based on their
username or groups they belong to, access to privileged commands. It can also be
used to run a command as a different user. The most basic setup allows people
wheel group to execute commands normally reserved for
Because sudo is a critical utility, it comes with its own editor that basically just wraps your preferred editor in a script that will complain if the configuration is wrong. To use this tool, invoke
Scroll to the line which contains
# %wheel ALL=(ALL) ALL, and remove the
We probably want to be able to login to the system as well. By default, users without passwords are disabled, so you'll need to set a password for the users you want to be able to use:
If you used a different username than
tyil, be sure to change it here as well.
Installation is now finished, so it is time to boot into your new Funtoo system. First you should cleanly unmount all partitions and then issue a reboot:
If you set your UEFI to favour the USB system over the standard drive in the booting order, be sure to either change this back, or simply remove the USB device.
First boot configurations
After your system has succesfully booted, login as root using the password you
passwd before rebooting.
Now you can finally setup the ZFS partition. Issue the following commands to
create a pool and a subvolume for
Create a user
Create a user for yourself on the system, as you should not perform regular
usage as root. You can use any other value for
tyil if you so desire:
-G wheel part is optional, but recommended if you wish to use this account
for administrative tasks. This option adds the user to the
wheel group, which
will allow the user to execute root commands using
Now you have a non-privileged user to login to. Log out of the root user by
exit. Next, log in on your normal user account.
Now you have a working Funtoo installation. Next steps would be installing all the software you wish to use and configuring it to your liking. I would greatly advise looking at other people's configurations and publishing your configurations as well. These configuration collections are often called dotfiles. Mine can be found on c.darenet.org.
If this is your first time using Funtoo as your distro of choice, I would recommend looking through Funtoo (GNU+)Linux First Steps on the official Funtoo wiki.
If you need assistance on maintainance, you can always drop by in