Gentoo Linux x86 Handbook
Sven Vermeulen Author
Grant Goodyear Author
Roy Marples Author
Daniel Robbins Author
Chris Houser Author
Jerry Alexandratos Author
Seemant Kulleen Gentoo x86 Developer
Tavis Ormandy Gentoo Alpha Developer
Jason Huebel Gentoo AMD64 Developer
Guy Martin Gentoo HPPA developer
Pieter Van den Abeele Gentoo PPC developer
Joe Kallar Gentoo SPARC developer
John P. Davis Editor
Pierre-Henri Jondot Editor
Eric Stockbridge Editor
Rajiv Manglani Editor
Jungmin Seo Editor
Stoyan Zhekov Editor
Jared Hudson Editor
Colin Morey Editor
Jorge Paulo Editor
Carl Anderson Editor
Jon Portnoy Editor
Zack Gilburd Editor
Jack Morgan Editor
Benny Chuang Editor
Erwin Editor
Joshua Kinard Editor
Tobias Scherbaum Editor
Xavier Neys Editor
Joshua Saddler Editor
Gerald J. Normandin Jr. Reviewer
Donnie Berkholz Reviewer
Ken Nowack Reviewer
Lars Weiler Contributor
Updated March 28, 2009
Content:
Installing Gentoo
In this part you learn how to install Gentoo on your system.
About the Gentoo Linux Installation
This chapter introduces you to the installation approach documented in this handbook.
1.
Choosing the Right Installation Medium
You can install Gentoo in many ways. This chapter explains how to install Gentoo using the minimal Installation CD
although installation through the Installer LiveCD is possible as well.
2.
Configuring your Network
To be able to download the latest source code, you will need to setup networking.
3.
Preparing the Disks
To be able to install Gentoo, you must create the necessary partitions. This chapter describes how to partition a disk for
future usage.
4.
Installing the Gentoo Installation Files
Gentoo installs work through a stage3 archive. In this chapter we describe how you extract the stage3 archive and
configure Portage.
5.
Installing the Gentoo Base System
After installing and configuring a stage3, the eventual result is that you have a Gentoo base system at your disposal. This
chapter describes how to progress to that state.
6.
Configuring the Kernel7.
Gentoo Linux Documentation -- Gentoo Linux x86 Handbook
http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?full=1&style...
1 of 87
4/15/2009 12:10 PM
The Linux kernel is the core of every distribution. This chapter explains how to configure your kernel.
Configuring your System
You need to edit some important configuration files. In this chapter you receive an overview of these files and an
explanation on how to proceed.
8.
Installing Necessary System Tools
In this chapter we help you choose and install some important tools.
9.
Configuring the Bootloader
Several bootloaders exist for the x86 architecture. Each one of them has its own way of configuration. We step you
through the process of configuring a bootloader to your needs.
10.
Finalizing your Gentoo Installation
You're almost done. We'll just create one (or more) users for your system.
11.
Where to go from here?
Now you have your Gentoo system, but what's next?
12.
Working with Gentoo
Learn how to work with Gentoo: installing software, altering variables, changing Portage behaviour etc.
A Portage Introduction
This chapter explains the "simple" steps a user definitely needs to know to maintain the software on his system.
1.
USE flags
USE flags are a very important aspect of Gentoo. In this chapter, you learn to work with USE flags and understand how
USE flags interact with your system.
2.
Portage Features
Discover the features Portage has, such as support for distributed compiling, ccache and more.
3.
Initscripts
Gentoo uses a special initscript format which, amongst other features, allows dependency-driven decisions and virtual
initscripts. This chapter explains all these aspects and explains how to deal with these scripts.
4.
Environment Variables
With Gentoo you can easily manage the environment variables for your system. This chapter explains how you do that,
and also describes frequently used variables.
5.
Working with Portage
"Working with Portage" provides an in-depth coverage of Portage, Gentoo's Software Management Tool.
Files and Directories
Once you want to know Portage in-depth you need to know where it stores its files and data.
1.
Configuring through Variables
Portage is completely configurable through various variables you can set in the configuration file or as environment
variable.
2.
Mixing Software Branches
Gentoo provides software separated in several branches, depending on stability and architectural support. "Mixing
Software Branches" inform you how these branches can be configured and how you can override this separation
individually.
3.
Additional Portage Tools
Portage comes with a few extra tools that might make your Gentoo experience even better. Read on to discover how to
use dispatch-conf and other tools.
4.
Diverting from the Official Tree
"Diverting from the Official Tree" gives you some tips and tricks on how to use your own Portage tree, how to
synchronise only the categories you want, inject packages and more.
5.
Gentoo Network Configuration
A comprehensive guide to Networking in Gentoo.
Getting Started
A guide to quickly get your network interface up and running in most common environments.
1.
Advanced Configuration
Here we learn about how the configuration works - you need to know this before we learn about modular networking.
2.
Modular Networking
Gentoo provides you flexible networking - here you are told about choosing different DHCP clients, setting up bonding,
bridging, VLANs and more.
3.
Wireless Networking
Wireless isn't straightforward. Hopefully we'll get you working!
4.
Adding Functionality
If you're feeling adventurous, you can add your own functions to networking.
5.
Network Management6.
Gentoo Linux Documentation -- Gentoo Linux x86 Handbook
http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?full=1&style...
2 of 87
4/15/2009 12:10 PM
For laptop users or people who move their computer around different networks.
A. Installing Gentoo
1. About the Gentoo Linux Installation
1.a. Introduction
Welcome!
First of all, welcome to Gentoo. You are about to enter the world of choices and performance. Gentoo is all about choices. When
installing Gentoo, this is made clear to you several times -- you can choose how much you want to compile yourself, how to install
Gentoo, what system logger you want, etc.
Gentoo is a fast, modern metadistribution with a clean and flexible design. Gentoo is built around free software and doesn't hide from
its users what is beneath the hood. Portage, the package maintenance system which Gentoo uses, is written in Python, meaning you
can easily view and modify the source code. Gentoo's packaging system uses source code (although support for precompiled
packages is included too) and configuring Gentoo happens through regular textfiles. In other words, openness everywhere.
It is very important that you understand that choices are what makes Gentoo run. We try not to force you onto anything you don't like. If
you feel like we do, please bugreport it.
How is the Installation Structured?
The Gentoo Installation can be seen as a 10-step procedure, corresponding to chapters 2 - 11. Every step results in a certain state:
After step 1, you are in a working environment ready to install Gentoo
After step 2, your internet connection is ready to install Gentoo
After step 3, your hard disks are initialized to house your Gentoo installation
After step 4, your installation environment is prepared and you are ready to chroot into the new environment
After step 5, core packages, which are the same on all Gentoo installations, are installed
After step 6, you have compiled your Linux kernel
After step 7, you have written most of your Gentoo system configuration files
After step 8, necessary system tools (which you can choose from a nice list) are installed
After step 9, your choice of bootloader has been installed and configured and you are logged in into your new Gentoo
installation
After step 10, your Gentoo Linux environment is ready to be explored
When you are given a certain choice, we try our best to explain what the pros and cons are. We will continue then with a default choice,
identified by "Default: " in the title. The other possibilities are marked by "Alternative: ". Do not think that the default is what we
recommend. It is however what we believe most users will use.
Sometimes you can pursue an optional step. Such steps are marked as "Optional: " and are therefore not needed to install Gentoo.
However, some optional steps are dependant on a previous decision you made. We will inform you when this happens, both when you
make the decision, and right before the optional step is described.
What are my Options?
You can install Gentoo in many different ways. You can download and install from one of our Installation CDs, from a distribution already
installed, from a bootable CD (such as Knoppix), from a netbooted environment, from a rescue floppy, etc.
This document covers the installation using a Gentoo Installation CD or, in certain cases, NetBooting. This installation assumes that you
want to install the latest available version of each package. If you want to perform a networkless installation, you should read the Gentoo
2008.0 Handbooks which contain the installation instructions for a networkless environment.
Also note that, if you plan on using GRP (the Gentoo Reference Platform, a collection of prebuilt packages meant for immediate use
after a Gentoo installation), you must follow the instructions in the Gentoo 2008.0 Handbooks.
For help on the other installation approaches, please read our Alternative Installation Guide. We also provide a Gentoo Installation Tips
& Tricks document that might be useful to read as well. If you feel that the current installation instructions are too elaborate, feel free to
use our Quick Installation Guide available from our Documentation Resources if your architecture has such a document available.
You also have several possibilities: you can compile your entire system from scratch or use a prebuilt environment to have your Gentoo
environment up and running in no time. And of course you have intermediate solutions in which you don't compile everything but start
Gentoo Linux Documentation -- Gentoo Linux x86 Handbook
http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?full=1&style...
3 of 87
4/15/2009 12:10 PM
from a semi-ready system.
Troubles?
If you find a problem in the installation (or in the installation documentation), please visit our bugtracking system and check if the bug is
known. If not, please create a bugreport for it so we can take care of it. Do not be afraid of the developers who are assigned to (your)
bugs -- they generally don't eat people.
Note though that, although the document you are now reading is architecture-specific, it will contain references to other architectures as
well. This is due to the fact that large parts of the Gentoo Handbook use source code that is common for all architectures (to avoid
duplication of efforts and starvation of development resources). We will try to keep this to a minimum to avoid confusion.
If you are uncertain if the problem is a user-problem (some error you made despite having read the documentation carefully) or a
software-problem (some error we made despite having tested the installation/documentation carefully) you are free to join #gentoo on
irc.freenode.net. Of course, you are welcome otherwise too :)
If you have a question regarding Gentoo, check out our Frequently Asked Questions, available from the Gentoo Documentation. You
can also view the FAQs on our forums. If you can't find the answer there ask on #gentoo, our IRC-channel on irc.freenode.net. Yes,
several of us are freaks who sit on IRC :-)
2. Choosing the Right Installation Medium
2.a. Hardware Requirements
Introduction
Before we start, we first list what hardware requirements you need to successfully install Gentoo on your box.
Hardware Requirements
Minimal CD LiveCD
CPU
i486 or later i686 or later
Memory
64 MB 256 MB
Diskspace
1.5 GB (excluding swap space)
Swap space
At least 256 MB
2.b. The Gentoo Installation CDs
Introduction
The Gentoo Installation CDs are bootable CDs which contain a self-sustained Gentoo environment. They allow you to boot Linux from
the CD. During the boot process your hardware is detected and the appropriate drivers are loaded. They are maintained by Gentoo
developers.
All Installation CDs allow you to boot, set up networking, initialize your partitions and start installing Gentoo from the Internet. We
currently provide two Installation CDs which are equally suitable to install Gentoo from, as long as you're planning on performing an
Internet-based installation using the latest version of the available packages.
Important: If you wish to install Gentoo without a working Internet connection, or would like to use one of the provided installers, please use the
installation instructions described in the Gentoo 2008.0 Handbooks.
The Installation CDs that we currently provide are:
The Gentoo Minimal Installation CD, a small, no-nonsense, bootable CD which sole purpose is to boot the system, prepare the
networking and continue with the Gentoo installation.
The Gentoo Installer LiveCD contains everything you need to install Gentoo. It provides a graphical environment, a graphical as
well as console based installer which automatically carries out the installation for you, and of course, the installation instructions
for your architecture.
To help you decide which Installation CD you need, we have written down the major advantages and disadvantages of each Installation
CD.
Gentoo Minimal Installation CD
Gentoo Linux Documentation -- Gentoo Linux x86 Handbook
http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?full=1&style...
4 of 87
4/15/2009 12:10 PM
The Minimal Installation CD is called install-x86-minimal-2008.0.iso and takes up only 57 MB of diskspace. You can use this
Installation CD to install Gentoo, but only with a working Internet connection.
Minimal Installation CD Pros and Cons
+
Smallest download
-
Contains no stage3 tarball, no Portage snapshot, no prebuilt packages and is therefore not suitable for networkless installation
Gentoo Installer LiveCD
The Installer LiveCD is called livecd-i686-installer-2008.0-r1.iso and takes up 655 MB. You can use this Installation CD to
install Gentoo, and you can even use it to install Gentoo without a working internet connection.
Installer LiveCD Pros and Cons
+
Contains everything you need. You can even install without a network conne ction.
-
Huge download
The Stage3 Tarball
A stage3 tarball is an archive containing a minimal Gentoo environment, suitable to continue the Gentoo installation using the
instructions in this manual. Previously, the Gentoo Handbook described the installation using one of three stage tarballs. While Gentoo
still offers stage1 and stage2 tarballs, the official installation method uses the stage3 tarball. If you are interested in performing a
Gentoo installation using a stage1 or stage2 tarball, please read the Gentoo FAQ on How do I Install Gentoo Using a Stage1 or Stage2
Tarball?
Stage3 tarballs can be downloaded from releases/x86/2008.0/stages/ on any of the Official Gentoo Mirrors and are not provided
on the LiveCD.
2.c. Download, Burn and Boot a Gentoo Installation CD
Downloading and Burning the Installation CDs
You have chosen to use a Gentoo Installation CD. We'll first start by downloading and burning the chosen Installation CD. We
previously discussed the several available Installation CDs, but where can you find them?
You can download any of the Installation CDs from one of our mirrors. The Installation CDs are located in the releases/x86/2008.0
/installcd/ directory.
Inside that directory you'll find ISO files. Those are full CD images which you can write on a CD-R.
In case you wonder if your downloaded file is corrupted or not, you can check its MD5 checksum and compare it with the MD5
checksum we provide (such as install-x86-minimal-2008.0.iso.DIGESTS). You can check the MD5 checksum with the md5sum
tool under Linux/Unix or md5sum for Windows.
Another way to check the validity of the downloaded file is to use GnuPG to verify the cryptographic signature that we provide (the file
ending with .asc). Download the signature file and obtain the public key:
Code Listing 3.1: Obtaining the public key
$ gpg --keyserver subkeys.pgp.net --recv-keys 17072058
Now verify the signature:
Code Listing 3.2: Verify the cryptographic signature
$ gpg --verify <signature file> <downloaded iso>
To burn the downloaded ISO(s), you have to select raw-burning. How you do this is highly program-dependent. We will discuss
cdrecord and K3B here; more information can be found in our Gentoo FAQ.
With cdrecord, you simply type cdrecord dev=/dev/hdc <downloaded iso file> (replace /dev/hdc with your CD-RW
drive's device path).
With K3B, select Tools > Burn CD Image. Then you can locate your ISO file within the 'Image to Burn' area. Finally click
Start.
Gentoo Linux Documentation -- Gentoo Linux x86 Handbook
http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?full=1&style...
5 of 87
4/15/2009 12:10 PM
