The last update to this installation guide was on April 2009, whether it is accurate still I can not say. Gentoo evolves gradually so for the most part it should be alright, best to use in reference with the Gentoo Handbook.
Installing Gentoo really is a breeze… once it has been done before. This guide is for installing Gentoo in a logical straight-forward manner. I have written everything generically, with necessary links for additional resource, look at the Gentoo Handbook from which this guide derives for more complex set-ups.
I choose to install from a LiveCD . I choose not to use Gentoo’s Minimal Install CD because many distro CD’s create a nice desktop to work on and a web browser can be useful to look up any questions.
Just about any Live CD a person has/likes can be used to install Gentoo with. For beginners it helps if it contains Gparted, an easy tool to partition with. If it doesn’t consider using Gparted’s LiveCD  to first partition the drive.
For security purposes and for convenience, I’d recommend having a partition for the system (root “
/“) and another for “
/home” (aka the users partition).
Linux uses a considerable less amount of memory than Windows or Mac OS X. Users with memory of 2GB or more probably don’t need a swap partition. If you choose not to have a swap partition and need to use swap, a swap file can be created later .
When done partitioning, restart and open the BIOS. Make sure the hardware clock is set to the right time, start the install disk and check the time in the terminal:
Possibly the installCD is using the UTC clock (Universal Time Clock – aka Greenwich Mean Time) for time and date and the clock will be skewed. This is not a problem. The correct settings will be entered on the new installation.
Gentoo will likely detect your network card and setup your network. If it doesn’t try the configuration utility:
You can find the name of your network device with ‘
Remote Install (Optional)
Some people may want to use another computer to install Gentoo from. This can be handy if say the remote machine has a bigger screen or has notes on it you’d like to access.
Begin by starting sshd on the computer to be installed upon:
How to start a daemon differs though per distribution. Give root a password on the machine to be installed on for security purposes:
Type “ifconfig” to find the internet address, then on the remote computer:
Preparing the Storage Unit
Mount the system partition created for the system install:
You can find out the partition you need to use with:
(e.g. /dev/hda3, or /dev/sda4) are examples of what your partition may be named.
A stage3 tarball will be needed now. Stage3 tarballs are tools and a base system that contains just enough necessary to boot your system. Gentoo builds regular stage3 tarballs. You should find the newest on the mirror (contained in /releases/<architecture>/autobuilds and download it.
On the LiveCD the internet networking needs to be working. Learn how to do this (it probably already is) and copy DNS info over to the system that is being built so the network will work on it:
/dev on the system being built:
Enter the new Gentoo environment by changing root:
chroot /mnt/gentoo /bin/bash env-update && source /etc/profile && sleep 2 && export PS1="(chroot) $PS1"
The Portage Tree (the software-repository) will need to be downloaded, this is done by:
Portage is the package installer for Gentoo. Gentoo does have some binary packages (packages pre-built) but mostly Gentoo is about compiling packages specific to your system.
For some reason Gentoo doesn’t add the portage configuration files:
Vim Default Editor (Optional)
I to do my editing with vim, why it’s not installed I don’t know.
Basic Settings – Add Timezone, Locales, Keymap
Set Time Type
Set time type to “local” if dual-booting Windows or Mac OS =<9. Later we’ll add an NTP program the syncs the time on boot, so it might be a good idea to edit “clock_systohc” to “YES” to keep the hardware clock in sync with Network Time Protocol.
Don’t bother to look at “date” as the chroot still uses the CD settings. The effect won’t be seen until you boot into your Gentoo system.
Locales provide information on regional settings – money type, character maps… To see available locales look at:
Set locales in:
Enter your locale. Here’s and example of the United States local setting:
To generate locale, run “locale-gen” and “locale” to check if the correct locale is set.
Keyboard Layout for Console
Available keymaps are in
The make files are basic settings for the system being built. There is the “
make.default” file that is the system profile for building a system. And there is the “
make.conf” file – a user-controlled profile that contains hardware information, properties wanted in packages (USE flags), and adds to or overrides the “
A system profile link to “
make.default” is set by default, make sure it is the correct one for the system:
Link to the most appropriate system profile:
The “desktop” and “server” subdirectories are optional but provide more detailed settings.
Confirm the link is correct:
“Make.conf” sits on top of the system profile choosen, adding and over-riding those settings. The most important item to a successful Gentoo build is providing as complete a “make.conf” as possible.
CHOST defines the basic architecture of the computer – 486,586,PPC… This is important to get right. It is alot of work and dangerous to try and fix this later in the build, research and be sure that it is right one.
CFLAGS are used to define the CPU architecture more specifically.
USE flags define options programs have that can be enabled or disabled. Try “
emerge -pv gcc” to see available flags.
It is nice to install Gentoo and have a reference to USE flags. You can install “gentoolkit” and use equery to find out about USE flags per packages:
The ACCEPT_KEYWORDS variable defines what software branch to use on the system. In Gentoo, there is a stable branch for already tested software and an experimental branch. If user is willing to test more recent software, consider using the testing branch, but expect more time debugging problems. To have Portage use the testing branch, add a ~ in front of the architecture.
VIDEO_CARDS define video card type. This value will tell xorg-server what video card drivers to pull in, and what DRI to use for the X server. Also a video card DRM is required either by selecting it in the kernel, x11-drm package, or the driver may have support for it: e.g. nvidia, ati, intel video card… A few values are available.
INPUT_DEVICES tells xorg-server what basic devices are or will be connected. Items include keyboard, mouse, touchpad…
GENTOO_MIRRORS are used for syncing the portage tree. You can test and add the three fastest mirrors by:
Beginning to Build
There will be a lot of compiling that can take several days to build on older computers. Portage is a well tested and complete compiling system and eases the process, but likely a few bugs will appear. A few tips:
Occasionally during compiling errors can occur. If choosing to use the unstable branch, the newest updates and less tested programs come with it. If there is a problem compiling along the way, check Dibb’s Package Page and revert back to an older version to compile. Or you can install eix (run eix-sync to update database) and do a quick search with “
Check the dependencies of a program to see if a dependency is causing the problem:
Custom USE Flags per Package
Apply custom USE flags for packages (e.g. “
media-sound/lame -gtk” removes the gtk dependencies of lame) and put in:
Read the Developer’s Notes After Emerging Packages
When emerging finishes developers will often leave notes about the program. It may mean more time and work but it is usually a good idea to follow them.
If you miss a note, developer notes are recorded in:
Installing a Kernel
The kernel contains the information of almost all the hardware on the computer and how to run it.
If this is the first time working with a kernel, I’d recommend using the genkernel – a basic all types kernel that will run on most systems.
Otherwise the configuration can be done manually. Manual configuring the kernel can make for a slightly faster boot but isn’t necessary in most cases. Manual configuration can take a long time though and requires alot of research, begin by:
Make sure the “
/usr/src/linux” link matches the downloaded kernel source:
Enter the directory and run “
make menuconfig” to get to the kernel configuration editor.
A Few Tips for Configuring the Kernel
- A good amount of details about the computer can be discovered with “
lspci” (part of the “pciutils” package).
lsusb” can be useful for USB hardware (“
lsusb” is part of the “usbutils” package).
- It’s a good idea to build sound support into the kernel if you need it.
- If unsure about an option, try adding it as a module – these can be specified to load or not load at boot time.
- More information can be found on the kernel in the Gentoo Handbook.
When the kernel config file is finished, compile the kernel, the modules, and install them:
Now the modules that were created need you need to specify which ones you need to boot.
find /lib/modules/ -type f -iname '*.o' -or -iname '*.ko'
Now add the ones needed to
/etc/modules.conf. Gentoo hasn’t added OpenRC to it’s stage3 yet but that should happen soon. When that happens you’ll have to add modules to
/etc/conf.d/modules. See the OpenRC migration guide for details.
The fstab file contains storage devices (drives and partitions), their mount points and any options that will mount at boot time. The “
/etc/fstab” file must be edited manually with the storage units you plan to be use.
An example fstab file:
Unique device nodes (UUID’s) can be used too that can prevent possible device conflicts. Take a look at this.
Setup the “
/etc/mtab” file here too. Usually the system discovers what filesystems are mounted and adds them to this file, but since this isn’t a full system yet, it needs to be created for your bootloader later:
Configuring the Network
Naming the pc is important so people on a network can recognize you. This is done with a hostname. A good practice is to name the computer <owner>-<machine> but people can name them anything – after famous philosophers, your favorite Gentoo developers… Open
Add the hostname boot script to run at startup:
Hostname will also need to be set in “
/etc/hosts” so some programs can become aware of it:
Setting a domainname is primarily used if the computer is to be server or if on a specialized network. Most people can ignore this setting.
Networking with DHCP
Most ISP’s (Internet Service Providers) use dhcp (network discovery) that makes setup easy.
Type “ifconfig” to see if your devices have been recognized. There should be a “lo” (loopback) device (necessary for some programs to access the network) a wired interface (eth0 is a common wired interface) and possibly a wireless interface (eth1, ath0…).
Any wired/wireless device will have to be linked to net.lo for the boot init system to recognize it.
Wait until reboot to see if the wired/wireless devices connect to the internet. Networks that require greater configuration can be done in “
/etc/conf.d/net“, see the Gentoo Documentation links below.
Now the init script needs to be added to load at boot:
Adding System Daemons and Tools
Daemons are constantly running programs that provide necessary services. Each service is listed below, or for ease of install, with one command:
The System Logger logs many events (good for debugging problems):
Cron Daemon schedules programs to run at a certain times.
Indexing Files for quick searches, use slocate to index files:
ACPI (Advanced Configuration and Power Interface) is used by most modern computers for power saving, suspend…
NTP client (Network Time Protocol) keeps the computer in sync with an internet time server.
File System Tools, if using another file system beside ext2/3, you’ll need their tools – xfsprogs, reiserfsprogs, jfsutils.
Check out what boot scripts are to load to be sure you got them all:
Adding Password and User
Root doesn’t have a password yet, so give it one and also create a new user.
If you need to create a regular user (not root) and you made a home partition (
/home) partition, it needs to be mounted now :
Now add a new user. Groups give the user permission to do certain tasks. Add a user to the wheel group to allow the user to ‘su’ to root. Other programs you add later may require you add a group to gain certian permissions (a developer note will usually tell you when you have to do this).
Configuring the Bootloader
A boot loader is required to load Linux. The boot loader should almost always be installed in the Master Boot Record (the first 512k of the disk – not partition). The MBR defines partitions, partition types, labels, whether it’s bootable… Getting this right is very important. Grub is the preferred bootloader, installing makes it the default system bootloader and will boot both Windows and Linux.
Grub nomenclature is different for devices. The first disk it recognizes is called “hd0“, the first partition it sees is “0” So the Linux root partition located on the first hard drive on the first partition, is labeled “hd0,0“.
First, the Grub configuration file (
/boot/grub/grub.conf) needs to be created manually:
Here’s a sample grub configuration file:
Grub also looks for kernel images relatively. So if a person has created a separate
/boot partition the correct path would be “
kernel-2.6.27” instead of “
The only require fields are default, timeout, title, root and kernel. You can also add password protection to the Grub, see Grub Password-Protection.
When done writing the grub file, create a link to it called
menu.lst (this is required because grub looks for this file):
Install Grub the Easy Way
Grub developers recommend using “
grub-install“, this usually works. If it doesn’t you’ll have to install grub manually.
“devincename” needs to be the hard disk your are installing Gentoo on. Often devicenames are “hda”, or “sda”. Grub needs to be installed at the beginning of the disk drive, not the partition.
Install Grub Manually
Now that your basic system is set up. Its a good time to see if it’s installed correctly. We’ll exit chroot here and umount the partitions:
Reboot (command is ‘
reboot‘) and test the new system.
After you see if it boots to a command prompt, I’d recommend rebooting back into the LiveCD, chrooting again, and building from there so you have a browser… to work with.
Now you should update everything. Even though the stage3 is fairly new a good number of changes may have been made already. You can update everything with:
With everything installed, now check that all library links meet their dependencies in case any breaks occured during the build (requires gentoolkit):
Now you can continue with the Gentoo documentation if for say you want to install a desktop.
For more on managing Gentoo take a look at Gentoo Linux Tidbits.
Troubleshooting and Notes
 If a distro CD refuses to boot, trying burning it to a DVD. Some BIOS’s have trouble with Linux CD’s.
 If needing to use swap later a swapfile can be created:
dd if=/dev/zero of=/swapfile bs=1024 count=2097152 mkswap /swapfile swapon /swapfile
 These two warnings will occur when there is no “
/home” partition mounted before adding a new user (i.e. a “/home/user” folder beneath the “/home” partition”):
xauth: timeout in locking authority file No directory, logging in with HOME=/
 With numerous kernel-sources, link “
/usr/src/linux” is best done by:
eselect kernel list eselect kernel set <no.>