Gentoo Quick Install

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 [1]. 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 [2] 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 [3].


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:

net-setup eth0

You can find the name of your network device with ‘ifconfig -a‘.

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:

/etc/init.d/sshd start

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:

ssh -l root@address

Preparing the Storage Unit

Mount the system partition created for the system install:

mount /dev/devicename /mnt/gentoo && cd /mnt/gentoo

You can find out the partition you need to use with:

fdisk -l

(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:

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

Mount /proc and /dev on the system being built:

mount -t proc none /mnt/gentoo/proc && mount -o bind /dev /mnt/gentoo/dev

Enter the new Gentoo environment by changing root:

chroot /mnt/gentoo /bin/bash
env-update && source /etc/profile && sleep 2 && export PS1="(chroot) $PS1"

Portage Configuration

The Portage Tree (the software-repository) will need to be downloaded, this is done by:

emerge –sync

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:

mkdir /etc/portage
touch /etc/portage/package.keywords
touch /etc/portage/package.use
touch /etc/portage/package.mask
touch /etc/portage/package.unmask

Vim Default Editor (Optional)

I to do my editing with vim, why it’s not installed I don’t know.

emerge vim

Basic Settings – Add Timezone, Locales, Keymap

Add timezone

ls /usr/share/zoneinfo
ln -sf /usr/share/zoneinfo/America/Chicago /etc/localtime

Set Time Type

vim /etc/conf.d/hwclock # or
vim /etc/conf.d/clock

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.

Glibc Locales

Locales provide information on regional settings – money type, character maps… To see available locales look at:

vim /usr/share/i18n/SUPPORTED

Set locales in:

vim /etc/locale.gen

Enter your locale. Here’s and example of the United States local setting:

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

To generate locale, run “locale-gen” and “locale” to check if the correct locale is set.

Update environment:

env-update && source /etc/profile

Keyboard Layout for Console

vim /etc/conf.d/keymaps

Available keymaps are in /usr/share/keymaps.

Make Files

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 “make.default” file.

A system profile link to “make.default” is set by default, make sure it is the correct one for the system:

ls -l /etc/make.profile

Link to the most appropriate system profile:

ln -sf /usr/portage/profiles/default/linux/<arch>/<gentoo-version-year>/<desktop|server…>

The “desktop” and “server” subdirectories are optional but provide more detailed settings.

Confirm the link is correct:

ls -l /etc/make.profile
… /etc/make.profile -> /usr/portage/profiles/default/linux/x86/<version>/


“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.

vim /etc/make.conf

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:

equery uses gcc

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:

mirrorselect -s3 -b10 -o -D >> /etc/make.conf

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:

Previous Versions

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 “eix <package>“.


Check the dependencies of a program to see if a dependency is causing the problem:

emerge -pv –tree <program>

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:

vim /etc/portage/package.use

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:

vim /var/log/portage/elog/summary.log

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:

emerge gentoo-sources
cd /usr/src/linux

Make sure the “/usr/src/linux” link matches the downloaded kernel source[5]:

ls -la /usr/src/linux

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:

make clean bzImage modules modules_install install

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.

Filesystem Information

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:

# /etc/fstab
# static file system details

# <file system> <mount point> <type> <options> <dump> <pass>
shm /dev/shm tmpfs nodev,nosuid,noexec 0 0
/dev/hda3 none swap sw 0 0
/dev/hda4 / ext3 noatime,defaults 0 1
/dev/cdrom /mnt/cdrom auto noauto,user 0 0

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:

grep -v rootfs /proc/mounts > /etc/mtab

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 /etc/conf.d/hostname


Add the hostname boot script to run at startup:

rc-update add hostname default

Hostname will also need to be set in “/etc/hosts” so some programs can become aware of it: smith-dell localhost

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.

ln -s /etc/init.d/net.lo /etc/init.d/net.eth0

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:

rc-update add net.eth0 default

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:

emerge sysklogd vixie-cron slocate ntp acpid \
&& rc-update add sysklogd default && \
rc-update add vixie-cron default && && rc-update add acpid default \
&& rc-update add ntp-client default

The System Logger logs many events (good for debugging problems):

emerge sysklogd && rc-update add sysklogd default

Cron Daemon schedules programs to run at a certain times.

emerge vixie-cron && rc-update add vixie-cron default

Indexing Files for quick searches, use slocate to index files:

emerge slocate

ACPI (Advanced Configuration and Power Interface) is used by most modern computers for power saving, suspend…

emerge acpid && rc-update add acpid default

NTP client (Network Time Protocol) keeps the computer in sync with an internet time server.

emerge ntp && rc-update add ntp-client default

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:

rc-update show

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 [4]:

mount /dev/devicename /home

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).

useradd -m -G adm,audio,cdrom,cdrw,cron,portage,users,usb,video,wheel -s /bin/bash USER
passwd USER

Warning: For the install, root user is being used for installing but besides this process it is not a good idea to log in as root. Login as regular user and use ’su‘ to log into root when you need administrative priveledges.

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:

# /boot/grub/grub.conf

# Default system to boot, 0 is first,…
# Timeout to wait before automatic loading of default system

title Gentoo Linux 2.6.27-r1
root (hd0,4)
kernel /boot/kernel-2.6.27 root=/dev/sda5

title Gentoo Linux 2.6.27 (Rescue)
root (hd0,4)
kernel /boot/kernel-2.6.27 root=/dev/sda5 init=/bin/bb

title Microsoft Windows Vista
rootnoverify (hd0,1)
chainloader +1

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 “/boot/kernel-2.6.27“.

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):

ln -sn /boot/grub/grub.conf /boot/grub/menu.lst

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.

grub-install –no-floppy /dev/devicename

“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

grub # Enters Grub shell
root (hd0,2) # Define where the “/” (aka root partition) lies”
setup (hd0) # Install Grub to the MBR


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:

exit && cd /
umount /mnt/gentoo/home /mnt/gentoo/dev /mnt/gentoo/proc /mnt/gentoo

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.

Final Touches

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:

emerge –update –newuse –deep world

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

[1] If a distro CD refuses to boot, trying burning it to a DVD. Some BIOS’s have trouble with Linux CD’s.

[2] If Gparted makes a Windows install unbootable read Recovering Windows Boot

[3] 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

[4] 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=/

[5] With numerous kernel-sources, link “/usr/src/linux” is best done by:

eselect kernel list
eselect kernel set <no.>

About Todd Partridge (Gently)

Good times, good people, good fun.

Posted on 2010-03-30, in Linux, Timely. Bookmark the permalink. 2 Comments.

  1. Pretty good! The best part is that you only have to do this once, everything is always fine after that, you just need sysrescuecd and a little patience. Once I helped a friend with 15s of `rm -fr /`, it took “only” 2 hours to be able to boot again, but time is never the factor with Gentoo.

  1. Pingback: gps time clock

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


Get every new post delivered to your Inbox.

Join 58 other followers

%d bloggers like this: