A complement to the official Gentoo Install Handbook

This is a step by step guide while installing Gentoo on a new box. Follow the instructions along with the official Installation Handbook from Gentoo.

Correctly choosing your hardware

Search the Internet before buying any hardware. Most hardware devices will work with Linux nowadays, but it is still better to buy hardware that has open-source drivers. You will also need to know which chipsets are on your hardware to correctly configure the kernel.

Choosing from which installation media you will boot

Booting from a Live CD

Choosing an installation CD seems harder that it first seems. For example, an installation CD for an x86 architecture won't work, if you want to install an AMD64 Gentoo.

• The installation CDs from Gentoo work fine, but they don't include X. You can still surf the web with links -g, and they contain relatively recent kernel, so it is not a bad choice.

• Apparently, there are now Live CDs from Gentoo, but I have not tried them yet.

• There are minimal Gentoo CDs that are handy. If your hardware is recognized, the best is to start ssh and login from a remote box, doing the installation from there. Not all kernel modules are built though.

• Knoppix Live CDs are good, but only for x86 (no amd64).

• Ubuntu Live CDs are probably the best choice. You can order them free of charge, and there is an amd64 live CD. On the latest Ubuntu CDs you can even get wifi networking painlessly! The only problem is that the root account is locked on Ubuntu, so you must use sudo all the time.
• If an Ubuntu live CD is not able to recognize correctly the hardware of your computer (recent hardware), usually the alphas of the next release (containing a more recent kernel) will work.
• To load sshd on an Ubuntu live cd, issue sudo apt-get install openssh-server. Then change the password of the current user (ubuntu) since ssh'ing into the box needs an non empty password.

Booting from an USB drive

• You should use the Etcher tool (not in official Portage, but present on overlays). It creates bootable keys from ISO files.
• The USB key should have a GPT partition table, and at least one partition with a VFAT (FAT 32) filesystem. The partition type should be EFI (ESP).
• On Windows Rufus is recommended.

Chrooting

• These are the correct commands from Ubuntu:

sudo mount --types proc /proc /mnt/gentoo/proc
sudo mount --rbind /sys /mnt/gentoo/sys
sudo mount --make-rslave /mnt/gentoo/sys
sudo mount --rbind /dev /mnt/gentoo/dev
sudo mount --make-rslave /mnt/gentoo/dev
sudo chroot /mnt/gentoo /bin/bash

Previous obsolete information

• This is sometimes mandatory for laptops that don't have optical drives (besides, it can be faster and easier). You can use the unetbootin tool (included in Portage). Note that unetbootin does not work well to create UEFI bootable keys.
• Follow the instructions there to format the USB drive (it seems to me very important to use W95 FAT32 as the partition type, *not* any other like W95 FAT32 (LBA) for instance). Also do not use Linux partition type!
• Sometimes the created USB key (via unetbootin) is still not bootable. In that case there is Rufus, a more powerful software that seems to work better, available on Windows. See instructions here.
• Be careful: do not use an amd64 live CD to install a 32 bit x86 version of Gentoo. Although most things seem to work fine, there are some obstacles (in my case the kernel would not compile correctly). Update: things should work OK if you use linux32 chroot instead of plain chroot.

Launching SSH daemon from Ubuntu

• Issue the following commands:

passwd ubuntu # you need to put a password for the ubuntu user
sudo apt install openssh-server # or sudo aptitude install openssh-server 
sudo /etc/init.d/ssh start

• Note that to enable root login (useful when copying over a previous Gentoo system), you would need:

passwd root
sudo nano /etc/ssh/sshd_config # add the line: PermitRootLogin yes
sudo /etc/init.d/ssh restart

Copying a previous Gentoo Linux installation

From the previous computer (pushing to the new one)

• In this case, you will need to setup the SSH daemon server on the target (new) computer.
• Copying everything can usually be done with the following commands (as root):

rsync -ave ssh /bin /boot /etc /home /lib /lib64 /opt /root /sbin /srv /usr /var root@192.168.0.5:/home/ubuntu/gentoo # /home/ubuntu/gentoo is where the partition is mounted on new computer
cp -a /bin /boot /etc /home /lib /lib64 /opt /root /sbin /usr /var /mnt/backup/ # same thing over a local hard drive
cd /mnt/previous && cp -a bin etc home lib lib64 opt root sbin usr var /mnt/backup/ # same thing over a local hard drive and a different boot OS (Ubuntu for instance)

From the new computer (pulling from the previous one)

• In this case, you will need to generate a new SSH key on the newly booted computer, then copy it to authorized_keys on the old one.
• Then run the following command:

sudo rsync -ave ssh root@192.168.0.5:/bin root@192.168.0.5:/boot root@192.168.0.5:/etc root@192.168.0.5:/home root@192.168.0.5:/lib root@192.168.0.5:/lib64 root@192.168.0.5:/opt root@192.168.0.5:/root root@192.168.0.5:/sbin root@192.168.0.5:/srv root@192.168.0.5:/usr root@192.168.0.5:/var /home/ubuntu/gentoo # /home/ubuntu/gentoo is where the partition is mounted on new computer

Follow-up

• Once you copied everything to the new partition, it is very common to have to update the kernel package (newer hardware may require a newer kernel). Don't forget to recreate (mkdir) the /dev, /proc, /run, /sys and /tmp directories. For /dev, you need to create at least the /dev/null and /dev/console (as of January, 2018).

cd /mnt/gentoo
mkdir dev proc run sys tmp
cd dev
mknod -m 660 console c 5 1
mknod -m 660 null c 1 3

• You may also need to change the Wifi firmware loaded into the kernel if the wifi card (Intel one) needs another one.
• Having to modify /etc/fstab, and checking the bootloader is also common.
• If you use rsync to make the copy (the issue does not appear with cp -a), a file on the dbus package gets systematically corrupted because it does not get the correct group id. The file is /usr/libexec/dbus-daemon-launch-helper and should have the following permissions and ownership (you can fix those manually if you cannot easily reemerge dbus):

-rws--x--- 1 root messagebus 56624 Jun 16  2017 /usr/libexec/dbus-daemon-launch-helper

• It's very important to rebuild dbus because lots of issues are present if this is not done (for instance, sound not working, restart and shutdown buttons absent on the KDE menu, USB keys not getting automounted, etc).

Installation following Gentoo's instructions

Useful configuration files from other Gentoo installs

• The following files can be useful on a USB key, to serve as a skeleton for the new install:
  • /etc/make.conf (to get your USE flags)
  • /var/lib/portage/world (a list of useful packages)
  • /usr/src/linux/.config (a kernel configuration)

Partitioning your hard drive

• Use gparted to resize some partitions, and fdisk to create or delete partitions.
• sfdisk (on the util-linux) package can also be useful, especially for changing the number of a partition. Use it like this:

sfdisk --dump /dev/sda > file.txt
# Now edit the file
sfdisk /dev/sda < file.txt

Be careful with this method though, you will probably have to reconfigure grub, and /etc/fstab.

Notes on official Gentoo's instructions

• At this point, boot from the CD, and setup the network (except if you booted with a Gentoo CD containing the handbook directly on it).

• Launch links -g (or better, Firefox if you booted into a CD offering X) to point a browser to the Gentoo Handbook. Once you have the handbook opened in a browser, follow the instructions.

• Partition your disk, format the partitions. Mount the root partition.

• Install the stage 3. With the new system, stage 3 tarballs are produced every week. Warning: get the correct stage 3 tarball! On x86 choose i686, not x86, for recent hardware. Then install a Portage snapshot.

• Be sure to choose the correct profile (the profile sets up some USE flags and other minor stuff). Usually the default profile is not the desktop profile.

• Configure /etc/make.conf. Don't forget to set:
  • correct CHOST;
  • correct CFLAGS;
  • your USE flags;

• chroot into the new partition (Use linux32 chroot if you booted from amd64 and want to install a 32 bit x86 architecture). emerge --sync. Configure the kernel. It is important to disable the nvidia framebuffer support. For NLS and FAT, choose the default NLS option / iocharset as "utf8", not "utf-8".

• Configure /etc/fstab, the network (don't forget to emerge dhcpcd if needed), /etc/rc.conf. If using DHCP, do not set "nodns" as an option on /etc/conf.d/net (even if it is the case on the handbook), or it will not setup DNS automatically. When choosing your HOSTNAME, be very careful not to include spaces! This will lead to severe failure later and KDE login will not work.

• Change the root password, add a normal user. Make sure the user has write permissions on its directory. Typically, if he doesn't, login into KDE will fail. The following groups should be added to this user:

wheel cdrom audio video games cdrw plugdev haldaemon messagebus portage

• Install and configure GRUB. The important thing is to add support for the framebuffer; if we don't, we won't be able to correctly use links when we reboot. Usually we will use a VESA framebuffer, although a new replacement exists called uvesa. This Wikipedia article lists some of the VESA modes; one way to obtain a list of VESA modes supported by this graphic card / BIOS is to put a wrong number. Then GRUB will display a list of available modes for this hardware.

• Reboot! On the BIOS, setup the clock according to the correct parameters in etc/conf.d/clock (UTC, or local time).

Installing packages and configuring the system

At this point, the goal is to get a working web browser again. So the first emerge should be something like emerge links. Be aware that some packages (from Sun, for example), need to be manually downloaded... and you don't have a browser yet! So you should add USE="-doc -java" to the first emerge. Alternatively, check if the package needs to be downloaded before the emerge (a F will appear next to the package). I recommend to use the emerge option "fetchonly" to see if everything was fetched correctly, before actually building.

Once links is emerged and works, the remaining of the installation is easier, since we have access to the web and Google.

• Install KDE and some web browsers: emerge kdebase-meta konqueror mozilla-firefox. This should again emerge a lot of packages. Don't forget to install the Flash plugin for Firefox, and the Java plugin as well. Note that installing kdebase-meta is mandatory, even with the kde USE flag the packages pulled in when you emerge konqueror are not enough to get a working KDE desktop.

• Configure X (Xorg -configure), add xdm to the runlevels: rc-update add xdm default. At this point we may even already switch to the nvidia driver for X. Edit the file /etc/conf.d/modules to get it automatically loaded. UPDATE: with recent Xorg versions, configuration is not even needed.

• Setup UTF-8 on the system.

• Allow your user to sudo. This is as simple as emerge sudo, and typing visudo as root to edit the configuration file (/etc/sudoers: do not edit this file by hand!).

• Install all the packages that you need. Integrate Thunderbird and Firefox.

emerge -a gentoolkit layman eix 
emerge -a acroread ark wine mozilla-thunderbird k3b mplayer vlc eclipse-sdk filezilla xchat kopete amarok openoffice-bin kdesvn

• Setup printers, if needed.

• Setup ALSA (the sound system).

• Make sure that all the users that need to mount removable media are in the 'plugdev' group, to get automounting to work correctly (among other things).

• If you need to mount NFS shares, add the nfsclient init script to the boot runlevel.

• Setup correct anti-aliasing and fonts.

• Optionally, install Beryl. Install Aquamarine along with Beryl, and install gtk-engines-qt in order to get your GTK applications use the KDE themes. UPDATE: install QtCurve rather than GTK-Qt; also you can use Xorg transparency effects rather than Beryl's one, they are stabler. For more information, see this page.