Gentoo Install Manual

Warning: the installation can differ from 3 hours to 3 days or more, depending on your installation complexity.

Booting up the CD

When booting up the CD you will be asked which kernel you want to load, I recommend going with the default kernel(Gentoo). So in the terminal type

gentoo

Then you will be asked which keyboard layout you want to use, just choose your current keyboard layout.

Connecting to the internet

I recommend doing this step through wired connection for easier setup.

If you want to use wifi, I recommend using wpa_supplicant for a setup, in that case type the next commands:

Type wpa_passphrase YOUR_WIFI_SSID_HERE YOUR_WIFI_PASSWORD_HERE > /etc/wpa_supplicant/wpa_supplicant.conf
Type wpa_supplicant -i YOUR_WIFI_INTERFACE -c /etc/wpa_supplicant/wpa_supplicant.conf &

This will use the file you created to connect to the wifi network.

Note: If you are using wpa_supplicant you might need to use the -D flag to choose your wifi adapter driver.

Partitioning

I personally recommend you partitioning your disk with the cfdisk tool for easier visualization of your disk. In this case I’ll be using a MBR(dos) partition type and I recommend creating a 2 primary partitions, one for the swap partition and one for the /(root) partition. When creating a swap partition make sure to change the partition type to Linux swap / Solaris.

Type mkswap /dev/YOUR_SWAP_PARTITION_ID to format the partition as a swap partition;
Type mkfs.ext4 /dev/YOUR_ROOT_PARTITION_ID to format your root partition as ext4;

Mounting partitions

Now we are going to mount the formatted partitions so we can then deploy the stage3 package.

Type swapon /dev/YOUR_SWAP_PARTITION_ID to activate your swap partition;
Type mount /dev/YOUR_ROOT_PARTITION_ID /mnt/gentoo to mount your root partition.

Installing stage3 tarball

cd /mnt/gentoo to go to the root partition directory;
links https://gentoo.org/downloads/ to open links, a ncurses based web browser and download the stage3 tarball from there;
After downloading the stage3 tarball type tar xpvf stage3-*.tar.xz --xattrs-include='*.*' --numeric-owner to unpack it to the root directory;
After unpacking the tarball you can now delete it rm -rf stage3-*.tar.xz.

Configuring your Compiler

In this phase you are going to configure portage, your package and “compiler”.

Type nano -w /mnt/gentoo/etc/portage/make.conf;

Now, in your make.conf file you’ll find something like this

# Compiler flags to set for all languages
COMMON_FLAGS="-march=native -O2 -pipe"
# Use the same settings for both variables
CFLAGS="${COMMON_FLAGS}"
CXXFLAGS="${COMMON_FLAGS}"

In your COMMON_FLAGS variable you can tune and optimize your compiler with certain CFLAGS based on your CPU.

According to the Gentoo Wiki:

A first setting is the -march= or -mtune= flag, which specifies the name of the target architecture.

A second one is the -O flag (that is a capital O, not a zero), which specifies the gcc optimization class flag. Possible classes are s (for size-optimized), 0 (zero - for no optimizations), 1, 2 or even 3 for more speed-optimization flags (every class has the same flags as the one before, plus some extras).-O2 is the recommended default. -O3 is known to cause problems when used system-wide, so we recommend to stick to -O2.

Another popular optimization flag is -pipe (use pipes rather than temporary files for communication between the various stages of compilation). It has no impact on the generated code, but uses more memory. On systems with low memory, gcc might get killed. In that case, do not use this flag.

Find out more specific CPU Optimizations here.

MAKEOPTS

The MAKEOPTS variable defines how many parallel compilations should occur when installing a package. A good choice is the number of CPUs (or CPU cores) in the system plus one. In case you want to use MAKEOPTS, you should add this to your make.conf file

MAKEOPTS="-jCPU_CORES_PLUS_ONE"

Setting up Gentoo Repos

OPTIONAL - Setting up Mirrors

This step is optional but since you may want to download your source code faster, you might want to set your nearest mirrors with the next command

mirrorselect -i -o >> /mnt/gentoo/etc/portage/make.conf

It will open up to you a ncurses complete list of mirrors where you with the spacebar select the ones nearest to you.

Gentoo ebuild repository

This file contains the sync information needed to update the package repository. To get this file to work type the next commands:

mkdir --parents /mnt/gentoo/etc/portage/repos.conf;
cp /mnt/gentoo/usr/share/portage/config/repos.conf /mnt/gentoo/etc/portage/repos.conf/gentoo.conf

Copying DNS Info

cp --dereference /etc/resolv.conf /mnt/gentoo/etc/

Mounting the remaining filesystems

Now that you setup your root partition, now you need to prepare the environment so you can chroot into the root partition, you can mount the necessary file systems with next commands

mount --types proc /proc /mnt/gentoo/proc
mount --rbind /sys /mnt/gentoo/sys
mount --make-rslave /mnt/gentoo/sys
mount --rbind /dev /mnt/gentoo/dev
mount --make-rslave /mnt/gentoo/dev
mount --bind /run /mnt/gentoo/run
mount --make-slave /mnt/gentoo/run

Entering the new environment

Since you mounted the remaining file systems you can now chroot into your Gentoo installation with the next commands

chroot /mnt/gentoo /bin/bash
source /etc/profile
export PS1="(chroot) ${PS1}"

Configuring Portage

Next step is to install a snapshot of the main ebuild repository. This snapshot contains a collection of files that informs Portage about available software titles (for installation), which profiles the system administrator can select, package or profile specific news items, etc. To download this snapshot type

emerge-webrsync

Updating ebuild repository

To sync portage with the snapshot you just downloaded type

emerge --sync

If you want to speedup the process by reducing frame buffers use

emerge --sync --quiet

OPTIONAL Set Up CCACHE

In Gentoo ccache helps avoid repeated recompilation for the same C and C++ object files by fetching result from a cache directory.

If you want to setup ccache, type the following commands

emerge --ask dev-util/ccache This command will install ccache;
mkdir -p /var/cache/ccache This will create a directory where C and C++ object files will be stored, you can set up the directory wherever you want, this is just the defaults;
chown root:portage /var/cache/ccache To give portage permissions to acess that directory;
chmod 2775 /var/cache/ccache Set this directory permissions.

Next up you configure ccache with the next config file at /var/cache/ccache/ccache.conf

# Maximum cache size to maintain
max_size = 100.0G

# Allow others to run 'ebuild' and share the cache.
umask = 002

# Preserve cache across GCC rebuilds and
# introspect GCC changes through GCC wrapper.
compiler_check = %compiler% -v

# I expect 1.5M files. 300 files per directory.
cache_dir_levels = 3

And finally you add a ccache entry in your portage make.conf file

FEATURES="ccache"
CCACHE_DIR="/var/cache/ccache"

You’re done, now your compilations will be much faster ;)

OPTIONAL cpuid2cpuflags

This tool guesses the host CPU_FLAGS_* based on their CPU. To get this tool to work, type the following commands

emerge --ask app-portage/cpuid2cpuflags This will install the tool;
mkdir -p /etc/portage/package.use This will create a directory where the flags will be stored;
echo "*/* $(cpuid2cpuflags)" > /etc/portage/package.use/00cpuflags This will link the cpuid2cpuflags to portage make.conf.

You are done, now you are squeezing a bit more of performance out of your CPU =)

Choosing your profile

A profile not only does it specify default values for USE, CFLAGS, and other important variables, it also locks the system to a certain range of package versions. You can see all the available profiles with eselect profile list, by default, it will preselect default/linux/amd64/17.1, and if you want to use your Gentoo system a desktop computer then you should select the default/linux/amd64/17.1/desktop profile, it will have the most appropriate USE and CFLAGS flags for your desktop daily use. Each profiles will have a correspondent number to it, so when you decide which profile you want to use, simply type

eselect profile set NUMBER_OF_PROFILE

Selecting your USE Flags

USE is one of the most powerful variables Gentoo provides to its users. Several programs can be compiled with or without optional support for certain items. For instance, some programs can be compiled with support for GTK+ or with support for Qt. Others can be compiled with or without SSL support. Some programs can even be compiled with frame buffer support (svgalib) instead of X11 support (X-server).

Most distributions compile their packages with support for as much as possible, increasing the size of the programs and startup time, not to mention an enormous amount of dependencies. With Gentoo users can define what options a package should be compiled with. This is where USE comes into play.

In the USE variable users define keywords which are mapped onto compile-options. For instance, ssl will compile SSL support in the programs that support it. -X will remove X-server support (note the minus sign in front). gnome gtk -kde -qt4 -qt5 will compile programs with GNOME (and GTK+) support, and not with KDE (and Qt) support, making the system fully tweaked for GNOME (if the architecture supports it).

If you want to know which USE flags come by default in your profile just type

emerge --info | grep ^USE

To manage your USE flags, you can manage them in your portage make.conf with the USE variable. For example, if you wanted to build a system based on qt and kde you would set this USE flags in your make.conf file

USE="-gtk -gnome qt4 qt5 kde"

Make sure you select the right USE flags at this step of installation, because if after you are fully setup and decide to change your global USE flags, you might have to wait tons of hours just to recompile your entire system with the new USE flags

You can check all the global USE flags here.

Updating and Recompiling the System

This following step is necessary so the system can apply any updates or USE flag changes which have appeared since the stage3 was built and from any profile selection

emerge --ask --verbose --update --deep --newuse @world

Notes:

Warning this might take a long time depending on the USE flags you set;
In this step you might need to use the command etc-update to fix some package dependencies or even you might need to do manual intervention to some of the packages depending on the compiler error.

Timezone

Now we start to install the actual system, first we need to choose a timezone, you can check the main available timezones with

ls /usr/share/zoneinfo

Once you chosen your directory option then use the same command but to see the sub-directories of your selected directory

ls /usr/share/zoneinfo/YOUR_SELECTED_MAIN_TIMEZONE/

Here you might choose the timezone that better suits you.

After you choose your timezone just add it to your etc directory with

echo "YOUR_SELECTED_MAIN_TIMEZONE/TIMEZONE_THAT_BETTER_SUITS_YOU" > /etc/timezone

Now, just reload your timezone settings to apply system-wide with

emerge --config sys-libs/timezone-data

Example

echo "Europe/Lisbon" > /etc/timezone

Locales

Locales specify not only the language that the user should use to interact with the system, but also what the rules are for sorting strings, displaying dates and times, etc.

To set locales, open the /etc/locale.gen file and uncomment the locales you want to use, for example, if you want to use the US locales, just uncomment the next lines

en_US ISO-8859-1
en_US.UTF-8 UTF-8

This will enable this locales and to generate the specified locales type

locale-gen

Now, to see the locales you can apply to your environment type

eselect locale list

You’ll see something like this

Available targets for the LANG variable:
  [1] C
  [2] POSIX
  [3] en_US
  [4] en_US.iso88591
  [5] en_US.utf8
  [ ] (free form)

And then, just like the profile you should select a locale number you prefer to apply to your LANG(language) variable, in this case I recommend to you, select a UTF8 locale. When you choose your locale, just type

eselect locale set NUMBER_OF_LOCALE

All you have to do now, is reload your environment with the new locale with the next command:

env-update && source /etc/profile && export PS1="(chroot) ${PS1}"

Grabbing the Kernel Sources

This is phase is based on the kernel compilation and installation, this can be saw has one of the most difficult steps as a Linux user, but once you overcome this step, you’ll see that it ain’t so hard to compile and customize 1. Grab the sources with emerge --ask sys-kernel/gentoo-sources sys-kernel/genkernel - If you need proprietary blobs also type emerge --ask sys-kernel/linux-firmware

From here and now on, you have two options

Configure manually the kernel(Recommended);
Generate a default Gentoo kernel with genkernel (Not recommended because, once you update your kernel, you’ll have to recompile the kernel with all the modules and quirks, while if you manually configure a kernel, you’ll have a faster and faster to compile kernel).

Compiling the kernel

Manually Configure the kernel

Warning: you might also need to make some changes to the kernel to suit better your system, these options below are just some base kernel functions.

Go to the kernel sources directory with cd /usr/src/linux;
Now you are going to open a ncurses based kernel configuration menu with make menuconfig, where you can toggle on a option with Y, or toggle off a option with N or simply make the options modules(By default once the kernel boots up they are off, but you can turn them on with modprobe DESIRED_MODULE_TO_TOGGLE_ON command) with M.

Activating required options

Make sure that every driver that is vital to the booting of the system (such as SCSI controller, etc.) is compiled in the kernel and not as a module, otherwise the system will not be able to boot completely.

Enabling devtmpfs support

Device Drivers --->
  Generic Driver Options --->
    [*] Maintain a devtmpfs filesystem to mount at /dev
    [*]   Automount devtmpfs at /dev, after the kernel mounted the rootfs

Enabling SCSI disk support

Device Drivers --->
   SCSI device support  --->
      <*> SCSI disk support

Selecting necessary file systems

Now go to File Systems and select support for the file systems you use. Don’t compile the file system that is used for the root file system as module, otherwise the Gentoo system will not be able to mount the partition. Also select Virtual memory and /proc file system. Select one or more of the following options as needed by the system.

File systems --->
  <*> Second extended fs support
  <*> The Extended 3 (ext3) filesystem
  <*> The Extended 4 (ext4) filesystem
  <*> Reiserfs support
  <*> JFS filesystem support
  <*> XFS filesystem support
  <*> Btrfs filesystem support
  DOS/FAT/NT Filesystems  --->
    <*> MSDOS fs support
    <*> VFAT (Windows-95) fs support

Pseudo Filesystems --->
    [*] /proc file system support
    [*] Tmpfs virtual memory file system support (former shm fs)

Selecting PPPoE necessary drivers

If PPPoE is used to connect to the Internet, or a dial-up modem, then enable the following options

Device Drivers --->
  Network device support --->
    <*> PPP (point-to-point protocol) support
    <*>   PPP support for async serial ports
    <*>   PPP support for sync tty ports

Activating SMP support

Processor type and features  --->
  [*] Symmetric multi-processing support

Activating USB support for input devices

Device Drivers --->
  HID support  --->
    -*- HID bus support
    <*>   Generic HID driver
    [*]   Battery level reporting for HID devices
      USB HID support  --->
	<*> USB HID transport layer
  [*] USB support  --->
    <*>     xHCI HCD (USB 3.0) support
    <*>     EHCI HCD (USB 2.0) support
    <*>     OHCI HCD (USB 1.1) support

Selecting processor types and features

Make sure to select IA32 Emulation if 32-bit programs should be supported.

Processor type and features  --->
   [ ] Machine Check / overheating reporting
   [ ]   Intel MCE Features
   [ ]   AMD MCE Features
   Processor family (AMD-Opteron/Athlon64)  --->
      ( ) Opteron/Athlon64/Hammer/K8
      ( ) Intel P4 / older Netburst based Xeon
      ( ) Core 2/newer Xeon
      ( ) Intel Atom
      ( ) Generic-x86-64
Executable file formats / Emulations  --->
   [*] IA32 Emulation

Enable support for GPT

Enable GPT partition label support if that was used previously when partitioning the disk

-*- Enable the block layer --->
   Partition Types --->
      [*] Advanced partition selection
      [*] EFI GUID Partition support

Enable support for UEFI

Enable EFI stub support and EFI variables in the Linux kernel if UEFI is used to boot the system

Processor type and features  --->
    [*] EFI runtime service support
    [*]   EFI stub support
    [*]     EFI mixed-mode support

Firmware Drivers  --->
    EFI (Extensible Firmware Interface) Support  --->
	<*> EFI Variable Support via sysfs

Kernel Extras

ALSA;
AMD GPU;
Android USB Tethering;
Dm-crypt;
Intel WiFi Drivers;
Intel CPU Performance Improved Performance Patch;
MMC - Device Drivers->MMC/SD/SDIO card support->Secure Digital Host Controller Interface support->SDHCI support on PCI bus;
Nvidia GPU;
OpenVPN;
Printing;
Pulseaudio;
QEMU;
VirtualBox.

From here, your system configurations may vary consonant your system, take a “trip” through the kernel menus and enable/disable the options that better suit you.

Compiling and Installing the kernel

Now that your kernel is configured, it’s time to compile it, type make && make modules_install to compile the kernel.

Now to install the kernel type make install. Finally you should generate initramfs of your kernel, so to do that, just type genkernel --install initramfs.

Note

You can then save your kernel configuration file (The file name .config inside your /usr/src/linux/ directory) wherever you want so if you need to recompile or reinstall the Gentoo kernel you just need to put the kernel configuration file inside of /usr/src/linux/.

Using Genkernel

If a manual configuration looks too daunting, then using genkernel is recommended. It will configure and build the kernel automatically. Just type genkernel all to generate the kernel.

Creating a fstab file

The /etc/fstab file uses a table-like syntax. Every line consists of six fields, separated by whitespace (space(s), tabs or a mixture). Each field has its own meaning:

The first field shows the block special device or remote file system to be mounted. Several kinds of device identifiers are available for block special device nodes, including paths to device files, file system labels and UUIDs, and partition labels and UUIDs. The second field shows the mount point at which the partition should be mounted. The third field shows the file system used by the partition. The fourth field shows the mount options used by mount when it wants to mount the partition. As every file system has its own mount options, users are encouraged to read the mount man page (man mount) for a full listing. Multiple mount options are comma-separated. The fifth field is used by dump to determine if the partition needs to be dumped or not. This can generally be left as 0 (zero). The sixth field is used by fsck to determine the order in which file systems should be checked if the system wasn’t shut down properly. The root file system should have 1 while the rest should have 2 (or 0 if a file system check isn’t necessary).

To start writting a fstab file you can start by typing the next command

blkid >> /etc/fstab

It will read your disks UUIDs and put them inside of your fstab file. Then type nano -w /etc/fstab to open up your fstab file, and modify it to look something like this, but with your UUIDs:

# /dev/YOUR_SWAP_PARTITION_ID
UUID=YOUR_SWAP_PARTITION_UUID       none            swap            sw              0 0

# /dev/YOUR_ROOT_PARTITION_ID
UUID=YOUR_ROOT_PARTITION_UUID       /               ext4            rw,relatime     0 1

Networking Information

Setting up Host name

Type

nano -w /etc/conf.d/hostname

And then change the host name variable to your desired variable.

Starting Networking at Boot

In this step, first you need to go into the init.d directory, so type

cd /etc/init.d

Then link your current interface to net.lo

ln -s net.lo net.YOUR_INTERNET_INTERFACE

Then add this link to openrc boot with

rc-update add net.YOUR_INTERNET_INTERFACE default

PCMCIA

If you are using PCMCIA then type

emerge --ask --quiet sys-apps/pcmciautils

System Configurations

Root password

Change your root password by typing:

passwd

Creating a user

Create a user by typing:

useradd -m -G wheel YOUR_DESIRED_USERNAME

Then create a password to that user by typing:

passwd YOUR_DESIRED_USERNAME

Boot configuration

Gentoo (at least when using OpenRC) uses /etc/rc.conf to configure the services, startup, and shutdown of a system. You should review most of these settings by typing

nano -w /etc/rc.conf

Now, you should change your tty keyboard layout inside of /etc/conf.d/keymaps with

nano -w /etc/conf.d/keymaps

If necessary change the hwclock with

nano -w /etc/conf.d/hwclock

System logger

Some tools are missing from the stage3 archive because several packages provide the same functionality. It is recommended the sysklogd package, so to get it and put it to working type:

emerge --quiet --ask app-admin/sysklogd
rc-update add sysklogd default

Cron daemon

A cron daemon executes scheduled commands. It is very handy if some command needs to be executed regularly (for instance daily, weekly or monthly). To setup cronie, type:

emerge --ask sys-process/cronie
rc-update add cronie default
crontab /etc/crontab

File indexing

In order to index the file system to provide faster file location capabilities, installmlocate with

emerge --ask sys-apps/mlocate

File systems

Depending on the file systems used, it is necessary to install the required file system utilities

File system	Package
Ext2, 3, and 4	sys-fs/e2fsprogs
VFAT (FAT32, …)	sys-fs/dosfstools
NTFS	sys-fs/ntfs3g
XFS	sys-fs/xfsprogs
ReiserFS	sys-fs/reiserfsprogs
JFS	sys-fs/jfsutils
Btrfs	sys-fs/btrfs-progs

Install your desired file system packages with

emerge --ask --quiet YOUR_DESIRED_FILESYSTEM_PACKAGES

Networking Tools

In order for the system to automatically obtain an IP address for one or more network interface(s) using netifrc scripts, it is necessary to install a DHCP client, to install it type:

emerge --quiet --ask net-misc/dhcpcd

OPTIONAL PPPoE client

If PPP is used to connect to the internet, install the net-dialup/ppp package with

emerge --ask net-dialup/ppp

OPTIONAL Wireless Networking

If the system will be connecting to wireless networks, install the next packages with

emerge --ask net-wireless/iw net-wireless/wpa_supplicant

Installing GRUB Boot loader

Install the grub with the next command

emerge --ask --quiet sys-boot/grub:2

After installing grub, install the boot loader with

grub-install /dev/YOUR_DISC_ID

Then generate a grub configuration file with

grub-mkconfig -o /boot/grub/grub.cfg

Finalize installation

Now to finalize the base initialize, exit chroot environment with

exit

Then unmount the pseudo file systems with

umount -l /mnt/gentoo/dev

And finally unmount your disk with

umount -R /mnt/gentoo

Now, reboot your system with the reboot command and enjoy your base system install.

Rafa's Website