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

• 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).
• 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).
• 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 aptitude install openssh-server
sudo /etc/init.d/ssh start

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; enable the VESA one though. 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/modules.autoload.d/kernel-2.6 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 portmap and nfs scripts to the default 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.