Install Gentoo


Wiki
Gentoo Linux amd64 Handbook: Installing Gentoo

< Handbook:AMD64 | Full
Contents [hide]
1 Introduction
1.1 Welcome
1.2 How the installation is structured
1.3 Installation options for Gentoo
1.4 Troubles
2 Hardware requirements
3 Gentoo Linux installation media
3.1 Minimal installation CD
3.2 The occasional Gentoo LiveDVD
3.3 What are stages then?
4 Downloading
4.1 Obtain the media
4.2 Verifying the downloaded files
4.2.1 Microsoft Windows based verification
4.2.2 Linux based verification
4.3 Burning a disk
4.3.1 Burning with Microsoft Windows
4.3.2 Burning with Linux
5 Booting
5.1 Booting the installation media
5.1.1 Kernel choices
5.1.2 Hardware options
5.1.3 Logical volume/device management
5.1.4 Other options
5.2 Extra hardware configuration
5.3 Optional: User accounts
5.4 Optional: Viewing documentation while installing
5.4.1 TTYs
5.4.2 GNU Screen
5.5 Optional: Starting the SSH daemon
6 Automatic network detection
6.1 Determine interface names
6.1.1 ifconfig command
6.1.2 ip command
6.2 Optional: Configure any proxies
6.3 Testing the network
7 Automatic network configuration
7.1 Default: Using net-setup
7.2 Alternative: Using PPP
7.3 Alternative: Using PPTP
8 Manual network configuration
8.1 Loading the appropriate network modules
8.2 Using DHCP
8.3 Preparing for wireless access
8.4 Understanding network terminology
8.5 Using ifconfig and route
9 Introduction to block devices
9.1 Block devices
9.2 Partition tables
9.2.1 MBR
9.2.2 GPT
9.3 GPT or MBR
9.3.1 Using UEFI
9.4 Advanced storage
9.4.1 Btrfs RAID
9.4.2 LVM
9.5 Default partitioning scheme
10 Designing a partition scheme
10.1 How many partitions and how big?
10.2 What about swap space?
10.3 What is the BIOS boot partition?
11 Default: Using parted to partition the disk
11.1 Viewing the current partition layout with parted
11.2 Setting the GPT label
11.3 Removing all partitions with parted
11.4 Creating the partitions
12 Alternative: Using fdisk to partition the disk
12.1 Viewing the current partition layout
12.2 Removing all partitions with fdisk
12.3 Creating the BIOS boot partition
12.4 Creating the boot partition
12.5 Creating the swap partition
12.6 Creating the root partition
12.7 Saving the partition layout
13 Creating file systems
13.1 Introduction
13.2 Filesystems
13.3 Applying a filesystem to a partition
13.4 Activating the swap partition
14 Mounting the root partition
15 Installing a stage tarball
15.1 Setting the date and time
15.1.1 Automatic
15.1.2 Manual
15.2 Choosing a stage tarball
15.2.1 Multilib (32 and 64-bit)
15.2.2 No-multilib (pure 64-bit)
15.3 Downloading the stage tarball
15.3.1 Graphical browsers
15.3.2 Command-line browsers
15.3.3 Verifying and validating
15.4 Unpacking the stage tarball
16 Configuring compile options
16.1 Introduction
16.2 CFLAGS and CXXFLAGS
16.3 MAKEOPTS
16.4 Ready, set, go!
17 Chrooting
17.1 Optional: Selecting mirrors
17.1.1 Distribution files
17.1.2 Gentoo ebuild repository
17.2 Copy DNS info
17.3 Mounting the necessary filesystems
17.4 Entering the new environment
17.5 Mounting the boot partition
18 Configuring Portage
18.1 Installing an ebuild repository snapshot from the web
18.2 Optional: Updating the Gentoo ebuild repository
18.3 Reading news items
18.4 Choosing the right profile
18.4.1 No-multilib
18.4.2 systemd
18.5 Updating the @world set
18.6 Configuring the USE variable
18.7 Optional: Configuring the ACCEPT_LICENSE variable
19 Optional: Using systemd as the init system
20 Timezone
21 Configure locales
22 Installing the sources
23 Default: Manual configuration
23.1 Introduction
23.2 Activating required options
23.3 Architecture specific kernel configuration
23.4 Compiling and installing
23.5 Optional: Building an initramfs
24 Alternative: Using genkernel
25 Kernel modules
25.1 Configuring the modules
25.2 Optional: Installing firmware
26 Filesystem information
26.1 About fstab
26.2 Creating the fstab file
26.2.1 Filesystem labels and UUIDs
26.2.2 Partition labels and UUIDs
27 Networking information
27.1 Host and domain information
27.2 Configuring the network
27.3 Automatically start networking at boot
27.4 The hosts file
27.5 Optional: Get PCMCIA working
28 System information
28.1 Root password
28.2 Init and boot configuration
29 System logger
30 Optional: Cron daemon
31 Optional: File indexing
32 Optional: Remote access
33 Filesystem tools
34 Networking tools
34.1 Installing a DHCP client
34.2 Optional: Installing a PPPoE client
34.3 Optional: Install wireless networking tools
35 Selecting a boot loader
36 Default: GRUB2
36.1 Emerge
36.2 Install
36.3 Configure
37 Alternative 1: LILO
37.1 Emerge
37.2 Configure
37.3 Install
38 Alternative 2: efibootmgr
39 Alternative 3: Syslinux
40 Rebooting the system
41 User administration
41.1 Adding a user for daily use
42 Disk cleanup
42.1 Removing tarballs
43 Where to go from here
43.1 Documentation
43.2 Gentoo online
43.2.1 Forums and IRC
43.2.2 Mailing lists
43.2.3 Bugs
43.2.4 Development guide
43.3 Closing thoughts
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 several times - users can choose how much they want to compile themselves, how to install Gentoo,
what system logger to use, etc.
Gentoo is a fast, modern meta-distribution with a clean and flexible design. It is built on an ecosystem of free software and does not hide
what is beneath the hood from its users. Portage, the package maintenance system which Gentoo uses, is written in Python, meaning
the user can easily view and modify the source code. Gentoo's packaging system uses source code (although support for pre-compiled
packages is included too) and configuring Gentoo happens through regular text files. In other words, openness everywhere.
It is very important that everyone understands that choices are what makes Gentoo run. We try not to force users into anything they do
not like. If anyone believes otherwise, please bug report it.
How the installation is structured

The Gentoo Installation can be seen as a 10-step procedure, corresponding to the next set of chapters. Each step results in a certain
state:
Step Result
1 The user is in a working environment ready to install Gentoo.
2 The Internet connection is ready to install Gentoo.
3 The hard disks are initialized to host the Gentoo installation.
4 The installation environment is prepared and the user is ready to chroot into the new environment.
5 Core packages, which are the same on all Gentoo installations, are installed.
6 The Linux kernel is installed.
7 The user will have configured most of the Gentoo system configuration files.
8 The necessary system tools are installed.
9 The proper boot loader has been installed and configured.
10 The freshly installed Gentoo Linux environment is ready to be explored.

Whenever a certain choice is presented the handbook will try to explain the pros and cons of each choice. Although the text then
continues with a default choice (identified by "Default: " in the title), the other possibilities will be documented as well (marked by
"Alternative: " in the title). Do not think that the default is what Gentoo recommends. It is however what Gentoo believes most users will
use.
Sometimes an optional step can be followed. Such steps are marked as "Optional: " and are therefore not needed to install Gentoo.
However, some optional steps are dependent on a previously made decision. The instructions will inform the reader when this happens,
both when the decision is made, and right before the optional step is described.
Installation options for Gentoo

Gentoo can be installed in many different ways. It can be downloaded and installed from official Gentoo installation media such as our
CDs and DVDs. The installation media can be installed on a USB stick or accessed via a netbooted environment. Alternatively, Gentoo
can be installed from non-official media such as an already installed distribution or a non-Gentoo bootable disk (such as Knoppix).
This document covers the installation using official Gentoo Installation media or, in certain cases, netbooting.

Note
For help on the other installation approaches, including using non-Gentoo CDs, please read our Alternative installation guide.
We also provide a Gentoo installation tips and tricks document that might be useful to read as well.
Troubles
If a problem is found in the installation (or in the installation documentation), please visit our bug tracking system and check if the bug
is known. If not, please create a bug report for it so we can take care of it. Do not be afraid of the developers who are assigned to the
bugs - they (generally) don't eat people.
Note though that, although this document is architecture-specific, it might contain references to other architectures as well. This is due to
the fact that large parts of the Gentoo Handbook use installation source text that is shared 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 there is some uncertainty whether or not the problem is a user-problem (some error made despite having read the documentation
carefully) or a software-problem (some error we made despite having tested the installation/documentation carefully) everybody is
welcome to join the #gentoo channel on irc.freenode.net. Of course, everyone is welcome otherwise too as our chat channel covers
the broad Gentoo spectrum.
Speaking of which, if there are any additional questions regarding Gentoo, check out the Frequently Asked Questions article. There are
also FAQs on the Gentoo Forums .
Hardware requirements
Before we start, we first list what hardware requirements are needed to successfully install Gentoo on a amd64 box.
AMD64 livedisk hardware requirements
Minimal CD LiveDVD
CPU Any AMD64 CPU or EM64T CPU (Core i3, i5, and i7 are EM64T)
Memory 256 MB 512 MB
Disk space 2.5 GB (excluding swap space)
Swap space At least 256 MB
The AMD64 project is a good place to be for more information about Gentoo's amd64 support.
Gentoo Linux installation media

Minimal installation CD

Note
As of August 23, 2018 the official Minimal CDs are capable of booting in UEFI mode. Previous versions boot in BIOS (MBR) mode
only. Readers looking to make their system UEFI bootable must download the latest ISO.
The Gentoo minimal installation CD is a bootable image which contains a self-sustained Gentoo environment. It allows the user to boot
Linux from the CD or other installation media. During the boot process the hardware is detected and the appropriate drivers are loaded.
The image is maintained by Gentoo developers and allows anyone to install Gentoo if an active Internet connection is available.
The Minimal Installation CD is called install-amd64-minimal-<release>.iso.
The occasional Gentoo LiveDVD

Occasionally, a special DVD is crafted by the Gentoo Ten project which can be used to install Gentoo. The instructions further down this
chapter target the Minimal Installation CD so might be a bit different. However, the LiveDVD (or any other bootable Linux environment)
supports getting a root prompt by just invoking sudo su - or sudo -i in a terminal.
What are stages then?

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/amd64/autobuilds/ on any of the official Gentoo mirrors . Stage files update
frequently and are not included on the installation images.
Downloading
Obtain the media
The default installation media that Gentoo Linux uses are the minimal installation CDs, which host a bootable, very small Gentoo Linux
environment. This environment contains all the right tools to install Gentoo. The CD images themselves can be downloaded from the
downloads page (recommended) or by manually browsing to the ISO location on one of the many available mirrors .
If downloading from a mirror, the minimal installation CDs can be found as follows:
1. Go to the releases/ directory.

2. Select the directory for the relevant target architecture (such as amd64/).
3. Select the autobuilds/ directory.
4. For amd64 and x86 architectures select either the current-install-amd64-minimal/ or current-install-x86-minimal/
directory (respectively). For all other architectures navigate to the current-iso/ directory.

Note
Some target architectures such as arm, mips, and s390 will not have minimal install CDs. At this time the Gentoo Release
Engineering project does not support building .iso files for these targets.
Inside this location, the installation media file is the file with the .iso suffix. For instance, take a look at the following listing:
CODE Example list of downloadable files at releases/amd64/autobuilds/current-iso/
[DIR] hardened/ 05-Dec-2014 01:42 -

[ ] install-amd64-minimal-20141204.iso 04-Dec-2014 21:04 208M
[ ] install-amd64-minimal-20141204.iso.CONTENTS 04-Dec-2014 21:04 3.0K
[ ] install-amd64-minimal-20141204.iso.DIGESTS 04-Dec-2014 21:04 740
[TXT] install-amd64-minimal-20141204.iso.DIGESTS.asc 05-Dec-2014 01:42 1.6K
[ ] stage3-amd64-20141204.tar.bz2 04-Dec-2014 21:04 198M
[ ] stage3-amd64-20141204.tar.bz2.CONTENTS 04-Dec-2014 21:04 4.6M
[ ] stage3-amd64-20141204.tar.bz2.DIGESTS 04-Dec-2014 21:04 720
[TXT] stage3-amd64-20141204.tar.bz2.DIGESTS.asc 05-Dec-2014 01:42 1.5K
In the above example, the install-amd64-minimal-20141204.iso file is the minimal installation CD itself. But as can be seen, other
related files exist as well:
A .CONTENTS file which is a text file listing all files available on the installation media. This file can be useful to verify if particular
firmware or drivers are available on the installation media before downloading it.
A .DIGESTS file which contains the hash of the ISO file itself, in various hashing formats/algorithms. This file can be used to verify if
the downloaded ISO file is corrupt or not.
A .DIGESTS.asc file which not only contains the hash of the ISO file (like the .DIGESTS file), but also a cryptographic signature of
that file. This can be used to both verify if the downloaded ISO file is corrupt or not, as well as verify that the download is indeed
provided by the Gentoo Release Engineering team and has not been tampered with.
Ignore the other files available at this location for now - those will come back when the installation has proceeded further. Download the
.iso file and, if verification of the download is wanted, download the .DIGESTS.asc file for the .iso file as well. The .CONTENTS file
does not need to be downloaded as the installation instructions will not refer to this file anymore, and the .DIGESTS file should contain
the same information as the .DIGESTS.asc file, except that the latter also contains a signature on top of it.
Verifying the downloaded files


Note
This is an optional step and not necessary to install Gentoo Linux. However, it is recommended as it ensures that the downloaded
file is not corrupt and has indeed been provided by the Gentoo Infrastructure team.
Through the .DIGESTS and .DIGESTS.asc files, the validity of the ISO file can be confirmed using the right set of tools. This verification
is usually done in two steps:
1. First, the cryptographic signature is validated to make sure that the installation file is provided by the Gentoo Release Engineering
team
2. If the cryptographic signature validates, then the checksum is verified to make sure that the downloaded file itself is not corrupted
Microsoft Windows based verification

On a Microsoft Windows system, chances are low that the right set of tools to verify checksums and cryptographic signatures are in
place.
To first verify the cryptographic signature, tools such as GPG4Win can be used. After installation, the public keys of the Gentoo
Release Engineering team need to be imported. The list of keys is available on the signatures page . Once imported, the user can then
verify the signature of the .DIGESTS.asc file.
 Important
This does not verify that the .DIGESTS file is correct, only that the .DIGESTS.asc file is. That also implies that the checksum should
be verified against the values in the .DIGESTS.asc file, which is why the instructions above only refer to downloading the
.DIGESTS.asc file.
The checksum itself can be verified using the Hashcalc application , although many others exist as well. Most of the time, these tools
will show the user the calculated checksum, and the user is requested to verify this checksum with the value that is inside the
.DIGESTS.asc file.
Linux based verification
On a Linux system, the most common method for verifying the cryptographic signature is to use the app-crypt/gnupg software. With
this package installed, the following commands can be used to verify the cryptographic signature of the .DIGESTS.asc file.
First, download the right set of keys as made available on the signatures page :
user $ gpg --keyserver hkps://hkps.pool.sks-keyservers.net --recv-keys 0xBB572E0E2D182910

gpg: requesting key 0xBB572E0E2D182910 from hkp server pool.sks-keyservers.net
gpg: key 0xBB572E0E2D182910: "Gentoo Linux Release Engineering (Automated Weekly Release Key) <releng@gent
oo.org>" 1 new signature
gpg: 3 marginal(s) needed, 1 complete(s) needed, classic trust model
gpg: depth: 0 valid: 3 signed: 20 trust: 0-, 0q, 0n, 0m, 0f, 3u
gpg: depth: 1 valid: 20 signed: 12 trust: 9-, 0q, 0n, 9m, 2f, 0u
gpg: next trustdb check due at 2018-09-15
gpg: Total number processed: 1
gpg: new signatures: 1
Alternatively you can use instead the WKD to download the key:
user $ wget -O- https://gentoo.org/.well-known/openpgpkey/hu/wtktzo4gyuhzu8a4z5fdj3fgmr1u6tob?l=releng |

gpg --import
--2019-04-19 20:46:32-- https://gentoo.org/.well-known/openpgpkey/hu/wtktzo4gyuhzu8a4z5fdj3fgmr1u6tob?l=r
eleng
Resolving gentoo.org (gentoo.org)... 89.16.167.134
Connecting to gentoo.org (gentoo.org)|89.16.167.134|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 35444 (35K) [application/octet-stream]
Saving to: 'STDOUT'
0K .......... .......... .......... .... 100% 11.9M=0.003s
2019-04-19 20:46:32 (11.9 MB/s) - written to stdout [35444/35444]
gpg: key 9E6438C817072058: 84 signatures not checked due to missing keys

gpg: /tmp/test2/trustdb.gpg: trustdb created
gpg: key 9E6438C817072058: public key "Gentoo Linux Release Engineering (Gentoo Linux Release Signing Key)
<[email protected]>" imported
gpg: key BB572E0E2D182910: 12 signatures not checked due to missing keys
gpg: key BB572E0E2D182910: 1 bad signature
gpg: key BB572E0E2D182910: public key "Gentoo Linux Release Engineering (Automated Weekly Release Key) <re
[email protected]>" imported
gpg: Total number processed: 2
gpg: imported: 2
gpg: no ultimately trusted keys found
Next verify the cryptographic signature of the .DIGESTS.asc file:
user $ gpg --verify install-amd64-minimal-20141204.iso.DIGESTS.asc

gpg: Signature made Fri 05 Dec 2014 02:42:44 AM CET
gpg: using RSA key 0xBB572E0E2D182910
gpg: Good signature from "Gentoo Linux Release Engineering (Automated Weekly Release Key) <[email protected]
rg>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: 13EB BDBE DE7A 1277 5DFD B1BA BB57 2E0E 2D18 2910
To be absolutely certain that everything is valid, verify the fingerprint shown with the fingerprint on the Gentoo signatures page .
With the cryptographic signature validated, next verify the checksum to make sure the downloaded ISO file is not corrupted. The
.DIGESTS.asc file contains multiple hashing algorithms, so one of the methods to validate the right one is to first look at the checksum
registered in the .DIGESTS.asc file. For instance, to get the SHA512 checksum:
user $ grep -A 1 -i sha512 install-amd64-minimal-20141204.iso.DIGESTS.asc

# SHA512 HASH
364d32c4f8420605f8a9fa3a0fc55864d5b0d1af11aa62b7a4d4699a427e5144b2d918225dfb7c5dec8d3f0fe2cddb7cc306da6f0c
ef4f01abec33eec74f3024 install-amd64-minimal-20141204.iso
--
# SHA512 HASH
0719a8954dc7432750de2e3076c8b843a2c79f5e60defe43fcca8c32ab26681dfb9898b102e211174a895ff4c8c41ddd9e9a00ad64
34d36c68d74bd02f19b57f install-amd64-minimal-20141204.iso.CONTENTS
In the above output, two SHA512 checksums are shown - one for the install-amd64-minimal-20141204.iso file and one for its
accompanying .CONTENTS file. Only the first checksum is of interest, as it needs to be compared with the calculated SHA512 checksum
which can be generated as follows:
user $ sha512sum install-amd64-minimal-20141204.iso

364d32c4f8420605f8a9fa3a0fc55864d5b0d1af11aa62b7a4d4699a427e5144b2d918225dfb7c5dec8d3f0fe2cddb7cc306da6f0c
ef4f01abec33eec74f3024 install-amd64-minimal-20141204.iso
As both checksums match, the file is not corrupted and the installation can continue.
Burning a disk
Of course, with just an ISO file downloaded, the Gentoo Linux installation cannot be started. The ISO file needs to be burned on a CD to
boot from, and in such a way that its content is burned on the CD, not just the file itself. Below a few common methods are described - a
more elaborate set of instructions can be found in Our FAQ on burning an ISO file.
Burning with Microsoft Windows

On Microsoft Windows, a number of tools exist that support burning ISOs on CDs.
With EasyCD Creator, select File, Record CD from CD image. Then change the Files of type to ISO image file. Then locate
the ISO file and click Open. After clicking on Start recording the ISO image will be burned correctly onto the CD-R.
With Nero Burning ROM, cancel the wizard which automatically pops up and select Burn Image from the File menu. Select the
image to burn and click Open. Now hit the Burn button and watch the brand new CD being burnt.
Burning with Linux

On Linux, the ISO file can be burned on a CD using the cdrecord command, part of the app-cdr/cdrtools package.
For instance, to burn the ISO file on the CD in the /dev/sr0 device (this is the first CD device on the system - substitute with the right
device file if necessary):
user $ cdrecord dev=/dev/sr0 install-amd64-minimal-20141204.iso
Users that prefer a graphical user interface can use K3B, part of the kde-apps/k3b package. In K3B, go to Tools and use Burn CD
Image. Then follow the instructions provided by K3B.
Booting
Booting the installation media
Once the installation media is ready, it is time to boot it. Insert the media in the system, reboot, and enter the motherboard's firmware
user interface. This is usually performed by pressing a keyboard key such as DEL , F1 , F10 , or ESC during the Power-On Self-test
(POST) process. The 'trigger' key varies depending on the system and motherboard. If it is not obvious use an internet search engine
and do some research using the motherboard's model name as the search keyword. Results should be easy to determine. Once inside
the motherboard's firmware menu, change the boot order so that the external bootable media (CD/DVD disks or USB drives) are tried
before the internal disk devices. Without this change, the system will most likely reboot to the internal disk device, ignoring the external
boot media.
 Important
When installing Gentoo with the purpose of using the UEFI interface instead of BIOS, it is recommended to boot with UEFI
immediately. If not, then it might be necessary to create a bootable UEFI USB stick (or other medium) once before finalizing the
Gentoo Linux installation.
If not yet done, ensure that the installation media is inserted or plugged into the system, and reboot. A boot prompt should be shown. At
this screen, Enter will begin the boot process with the default boot options. To boot the installation media with custom boot options,
specify a kernel followed by boot options and then hit Enter .
At the boot prompt, users get the option of displaying the available kernels ( F1 ) and boot options ( F2 ). If no choice is made within 15
seconds (either displaying information or using a kernel) then the installation media will fall back to booting from disk. This allows
installations to reboot and try out their installed environment without the need to remove the CD from the tray (something well
appreciated for remote installations).
Specifying a kernel was mentioned. On the Minimal installation media, only two predefined kernel boot options are provided. The default
option is called gentoo. The other being the -nofb variant; this disables kernel framebuffer support.
The next section displays a short overview of the available kernels and their descriptions:
Kernel choices
gentoo
Default kernel with support for K8 CPUs (including NUMA support) and EM64T CPUs.
gentoo-nofb
Same as gentoo but without framebuffer support.
memtest86
Test the local RAM for errors.
Alongside the kernel, boot options help in tuning the boot process further.
Hardware options
acpi=on
This loads support for ACPI and also causes the acpid daemon to be started by the CD on boot. This is only needed if the system
requires ACPI to function properly. This is not required for Hyperthreading support.
acpi=off
Completely disables ACPI. This is useful on some older systems and is also a requirement for using APM. This will disable any
Hyperthreading support of your processor.
console=X
This sets up serial console access for the CD. The first option is the device, usually ttyS0 on x86, followed by any connection options,
which are comma separated. The default options are 9600,8,n,1.
dmraid=X
This allows for passing options to the device-mapper RAID subsystem. Options should be encapsulated in quotes.
doapm
This loads APM driver support. This also requires that acpi=off .
dopcmcia
This loads support for PCMCIA and Cardbus hardware and also causes the pcmcia cardmgr to be started by the CD on boot. This is
only required when booting from PCMCIA/Cardbus devices.
doscsi
This loads support for most SCSI controllers. This is also a requirement for booting most USB devices, as they use the SCSI
subsystem of the kernel.
sda=stroke
This allows the user to partition the whole hard disk even when the BIOS is unable to handle large disks. This option is only used on
machines with an older BIOS. Replace sda with the device that requires this option.
ide=nodma
This forces the disabling of DMA in the kernel and is required by some IDE chipsets and also by some CDROM drives. If the system
is having trouble reading from the IDE CDROM, try this option. This also disables the default hdparm settings from being executed.
noapic
This disables the Advanced Programmable Interrupt Controller that is present on newer motherboards. It has been known to cause
some problems on older hardware.
nodetect
This disables all of the autodetection done by the CD, including device autodetection and DHCP probing. This is useful for doing
debugging of a failing CD or driver.
nodhcp
This disables DHCP probing on detected network cards. This is useful on networks with only static addresses.
nodmraid
Disables support for device-mapper RAID, such as that used for on-board IDE/SATA RAID controllers.
nofirewire
This disables the loading of Firewire modules. This should only be necessary if your Firewire hardware is causing a problem with
booting the CD.
nogpm
This disables gpm console mouse support.
nohotplug
This disables the loading of the hotplug and coldplug init scripts at boot. This is useful for doing debugging of a failing CD or driver.
nokeymap
This disables the keymap selection used to select non-US keyboard layouts.
nolapic
This disables the local APIC on Uniprocessor kernels.
nosata
This disables the loading of Serial ATA modules. This is used if the system is having problems with the SATA subsystem.
nosmp
This disables SMP, or Symmetric Multiprocessing, on SMP-enabled kernels. This is useful for debugging SMP-related issues with
certain drivers and motherboards.
nosound
This disables sound support and volume setting. This is useful for systems where sound support causes problems.
nousb
This disables the autoloading of USB modules. This is useful for debugging USB issues.
slowusb
This adds some extra pauses into the boot process for slow USB CDROMs, like in the IBM BladeCenter.
Logical volume/device management

dolvm
This enables support for Linux's Logical Volume Management.
Other options
debug
Enables debugging code. This might get messy, as it displays a lot of data to the screen.
docache
This caches the entire runtime portion of the CD into RAM, which allows the user to umount /mnt/cdrom and mount another
CDROM. This option requires that there is at least twice as much available RAM as the size of the CD.
doload=X
This causes the initial ramdisk to load any module listed, as well as dependencies. Replace X with the module name. Multiple
modules can be specified by a comma-separated list.
dosshd
Starts sshd on boot, which is useful for unattended installs.
passwd=foo
Sets whatever follows the equals as the root password, which is required for dosshd since the root password is by default scrambled.
noload=X
This causes the initial ramdisk to skip the loading of a specific module that may be causing a problem. Syntax matches that of doload.
nonfs
Disables the starting of portmap/nfsmount on boot.
nox
This causes an X-enabled LiveCD to not automatically start X, but rather, to drop to the command line instead.
scandelay
This causes the CD to pause for 10 seconds during certain portions the boot process to allow for devices that are slow to initialize to
be ready for use.
scandelay=X
This allows the user to specify a given delay, in seconds, to be added to certain portions of the boot process to allow for devices that
are slow to initialize to be ready for use. Replace X with the number of seconds to pause.

Note
The bootable media will check for no* options before do* options, so that options can be overridden in the exact order specified.
Now boot the media, select a kernel (if the default gentoo kernel does not suffice) and boot options. As an example, we boot the gentoo
kernel, with dopcmcia as a kernel parameter:
boot: gentoo dopcmcia
Next the user will be greeted with a boot screen and progress bar. If the installation is done on a system with a non-US keyboard, make
sure to immediately press Alt + F1 to switch to verbose mode and follow the prompt. If no selection is made in 10 seconds the default
(US keyboard) will be accepted and the boot process will continue. Once the boot process completes, the user is automatically logged in
to the "Live" Gentoo Linux environment as the root user, the super user. A root prompt is displayed on the current console, and one can
switch to other consoles by pressing Alt + F2 , Alt + F3 and Alt + F4 . Get back to the one started on by pressing Alt + F1 .
Extra hardware configuration

When the Installation medium boots, it tries to detect all the hardware devices and loads the appropriate kernel modules to support the
hardware. In the vast majority of cases, it does a very good job. However, in some cases it may not auto-load the kernel modules
needed by the system. If the PCI auto-detection missed some of the system's hardware, the appropriate kernel modules have to be
loaded manually.
In the next example the 8139too module (which supports certain kinds of network interfaces) is loaded:
root # modprobe 8139too
Optional: User accounts

If other people need access to the installation environment, or there is need to run commands as a non-root user on the installation
medium (such as to chat using irssi without root privileges for security reasons), then an additional user account needs to be created
and the root password set to a strong password.
To change the root password, use the passwd utility:
root # passwd
New password: (Enter the new password)
Re-enter password: (Re-enter the password)
To create a user account, first enter their credentials, followed by the account's password. The useradd and passwd commands are
used for these tasks.
In the next example, a user called john is created:
root # useradd -m -G users john

root # passwd john
New password: (Enter john's password)
Re-enter password: (Re-enter john's password)
To switch from the (current) root user to the newly created user account, use the su command:
root # su - john
Optional: Viewing documentation while installing

TTYs
To view the Gentoo handbook during the installation, first create a user account as described above. Then press Alt + F2 to go to a
new terminal.
During the installation, the links command can be used to browse the Gentoo handbook - of course only from the moment that the
Internet connection is working.
user $ links https://wiki.gentoo.org/wiki/Handbook:AMD64
To go back to the original terminal, press Alt + F1 .
GNU Screen
The Screen utility is installed by default on official Gentoo installation media. It may be more efficient for the seasoned Linux enthusiast to
use screen to view installation instructions via split panes rather than the multiple TTY method mentioned above.
Optional: Starting the SSH daemon

To allow other users to access the system during the installation (perhaps to support during an installation, or even do it remotely), a
user account needs to be created (as was documented earlier on) and the SSH daemon needs to be started.
To fire up the SSH daemon on an OpenRC init, execute the following command:
root # rc-service sshd start

Note
If users log on to the system, they will see a message that the host key for this system needs to be confirmed (through what is
called a fingerprint). This behavior is typical and can be expected for initial connections to an SSH server. However, later when the
system is set up and someone logs on to the newly created system, the SSH client will warn that the host key has been changed.
This is because the user now logs on to - for SSH - a different server (namely the freshly installed Gentoo system rather than the
live environment that the installation is currently using). Follow the instructions given on the screen then to replace the host key on
the client system.
To be able to use sshd, the network needs to function properly. Continue with the chapter on Configuring the network.
Automatic network detection
Maybe it just works?
If the system is plugged into an Ethernet network with a DHCP server, it is very likely that the networking configuration has already been
set up automatically. If so, then the many included network-aware commands on the installation CD such as ssh, scp, ping, irssi,
wget, and links, among others, will work immediately.
Determine interface names

ifconfig command
If networking has been configured, the ifconfig command should list one or more network interfaces (besides lo). In the example
below eth0 shows up:
root # ifconfig
eth0 Link encap:Ethernet HWaddr 00:50:BA:8F:61:7A
inet addr:192.168.0.2 Bcast:192.168.0.255 Mask:255.255.255.0
inet6 addr: fe80::50:ba8f:617a/10 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:1498792 errors:0 dropped:0 overruns:0 frame:0
TX packets:1284980 errors:0 dropped:0 overruns:0 carrier:0
collisions:1984 txqueuelen:100
RX bytes:485691215 (463.1 Mb) TX bytes:123951388 (118.2 Mb)
Interrupt:11 Base address:0xe800
As a result of the shift towards predictable network interface names , the interface name on the system can be quite different from the
old eth0 naming convention. Recent installation media might show regular network interfaces names like eno0, ens1, or enp5s0. Look
for the interface in the ifconfig output that has an IP address related to the local network.
 Tip
If no interfaces are displayed when the standard ifconfig command is used, try using the same command with the -a option.
This option forces the utility to show all network interfaces detected by the system whether they be in an up or down state. If
ifconfig -a produces no results then the hardware is faulty or the driver for the interface has not been loaded into the kernel.
Both situations reach beyond the scope of this Handbook. Contact #gentoo for support.
ip command
As an alternative to ifconfig, the ip command can be used to determine interface names. The following example shows the output of
ip addr (of another system so the information shown is different from the previous example):
root # ip addr
2: eno1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
link/ether e8:40:f2:ac:25:7a brd ff:ff:ff:ff:ff:ff
inet 10.0.20.77/22 brd 10.0.23.255 scope global eno1
valid_lft forever preferred_lft forever
inet6 fe80::ea40:f2ff:feac:257a/64 scope link
valid_lft forever preferred_lft forever
The output above may be a bit more complicated to read than alternative. The interface name in the above example directly follows the
number; it is eno1.
In the remainder of this document, the handbook will assume that the operating network interface is called eth0.
Optional: Configure any proxies

If the Internet is accessed through a proxy, then it is necessary to set up proxy information during the installation. It is very easy to define
a proxy: just define a variable which contains the proxy server information.
In most cases, it is sufficient to define the variables using the server hostname. As an example, we assume the proxy is called
proxy.gentoo.org and the port is 8080.
To set up an HTTP proxy (for HTTP and HTTPS traffic):
root # export http_proxy="http://proxy.gentoo.org:8080"
To set up an FTP proxy:
root # export ftp_proxy="ftp://proxy.gentoo.org:8080"
To set up an RSYNC proxy:

root # export RSYNC_PROXY="proxy.gentoo.org:8080"
If the proxy requires a username and password, use the following syntax for the variable:
CODE Adding username/password to the proxy variable
http://username:[email protected]:8080
Testing the network

Try pinging your ISP's DNS server (found in /etc/resolv.conf) and a web site of choice. This ensures that the network is functioning
properly and that the network packets are reaching the net, DNS name resolution is working correctly, etc.
root # ping -c 3 www.gentoo.org
If this all works, then the remainder of this chapter can be skipped to jump right to the next step of the installation instructions (Preparing
the disks).
Automatic network configuration

If the network doesn't work immediately, some installation media allow the user to use net-setup (for regular or wireless networks),
pppoe-setup (for ADSL users) or pptp (for PPTP users).
If the installation medium does not contain any of these tools, continue with the Manual network configuration.
Regular Ethernet users should continue with Default: Using net-setup

ADSL users should continue with Alternative: Using PPP
PPTP users should continue with Alternative: Using PPTP
Default: Using net-setup

The simplest way to set up networking if it didn't get configured automatically is to run the net-setup script:
root # net-setup eth0
net-setup will ask some questions about the network environment. When all is done, the network connection should work. Test the
network connection as stated before. If the tests are positive, congratulations! Skip the rest of this section and continue with Preparing
the disks.
If the network still doesn't work, continue with Manual network configuration.
Alternative: Using PPP

Assuming PPPoE is needed to connect to the Internet, the installation CD (any version) has made things easier by including ppp. Use the
provided pppoe-setup script to configure the connection. During the setup the Ethernet device that is connected to your ADSL modem,
the username and password, the IPs of the DNS servers and if a basic firewall is needed or not will be asked.
root # pppoe-setup
root # pppoe-start
If something goes wrong, double-check that the username and password are correct by looking at etc/ppp/pap-secrets or
/etc/ppp/chap-secrets and make sure to use the right Ethernet device. If the Ethernet device does not exist, the appropriate network
modules need to be loaded. In that case continue with Manual network configuration as it will explain how to load the appropriate
network modules there.
If everything worked, continue with Preparing the disks.
Alternative: Using PPTP

If PPTP support is needed, use pptpclient which is provided by the installation CDs. But first make sure that the configuration is
correct. Edit /etc/ppp/pap-secrets or /etc/ppp/chap-secrets so it contains the correct username/password combination:
root # nano -w /etc/ppp/chap-secrets
Then adjust /etc/ppp/options.pptp if necessary:
root # nano -w /etc/ppp/options.pptp
When all that is done, run pptp (along with the options that couldn't be set in options.pptp) to connect the server:
root # pptp <server ip>
Now continue with Preparing the disks.
Manual network configuration

Loading the appropriate network modules
When the Installation CD boots, it tries to detect all the hardware devices and loads the appropriate kernel modules (drivers) to support
the hardware. In the vast majority of cases, it does a very good job. However, in some cases, it may not auto-load the kernel modules
needed.
If net-setup or pppoe-setup failed, then it is possible that the network card wasn't found immediately. This means users may have to
load the appropriate kernel modules manually.
To find out what kernel modules are provided for networking, use the ls command:
root # ls /lib/modules/`uname -r`/kernel/drivers/net
If a driver is found for the network device, use modprobe to load the kernel module. For instance, to load the pcnet32 module:
root # modprobe pcnet32
To check if the network card is now detected, use ifconfig. A detected network card would result in something like this (again, eth0
here is just an example):
root # ifconfig eth0

eth0 Link encap:Ethernet HWaddr FE:FD:00:00:00:00
BROADCAST NOARP MULTICAST MTU:1500 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:0 (0.0 b) TX bytes:0 (0.0 b)
If however the following error is shown, the network card is not detected:
root # ifconfig eth0

eth0: error fetching interface information: Device not found
The available network interface names on the system can be listed through the /sys file system:
root # ls /sys/class/net
dummy0 eth0 lo sit0 tap0 wlan0
In the above example, 6 interfaces are found. The eth0 one is most likely the (wired) Ethernet adapter whereas wlan0 is the wireless
one.
Assuming that the network card is now detected, retry net-setup or pppoe-setup again (which should work now), but for the hardcore
people we explain how to configure the network manually as well.
Select one of the following sections based on your network setup:
Using DHCP for automatic IP retrieval

Preparing for wireless access if a wireless network is used
Understanding network terminology explains the basics about networking
Using ifconfig and route explains how to set up networking manually
Using DHCP
DHCP (Dynamic Host Configuration Protocol) makes it possible to automatically receive networking information (IP address, netmask,
broadcast address, gateway, nameservers etc.). This only works if a DHCP server is in the network (or if the ISP provider provides a
DHCP service). To have a network interface receive this information automatically, use dhcpcd:
root # dhcpcd eth0
Some network administrators require that the hostname and domainname provided by the DHCP server is used by the system. In that
case, use:
root # dhcpcd -HD eth0
If this works (try pinging some Internet server, like Google's 8.8.8.8 or Cloudflare's 1.1.1.1), then everything is set and ready to continue.
Skip the rest of this section and continue with Preparing the disks.
Preparing for wireless access


Note
Support for the iw command might be architecture-specific. If the command is not available see if the net-wireless/iw package is
available for the current architecture. The iw command will be unavailable unless the net-wireless/iw package has been installed.
When using a wireless (802.11) card, the wireless settings need to be configured before going any further. To see the current wireless
settings on the card, one can use iw. Running iw might show something like:
root # iw dev wlp9s0 info

Interface wlp9s0
ifindex 3
wdev 0x1
addr 00:00:00:00:00:00
type managed
wiphy 0
channel 11 (2462 MHz), width: 20 MHz (no HT), center1: 2462 MHz
txpower 30.00 dBm
To check for a current connection:
root # iw dev wlp9s0 link

Not connected.
or
root # iw dev wlp9s0 link

Connected to 00:00:00:00:00:00 (on wlp9s0)
SSID: GentooNode
freq: 2462
RX: 3279 bytes (25 packets)
TX: 1049 bytes (7 packets)
signal: -23 dBm
tx bitrate: 1.0 MBit/s

Note
Some wireless cards may have a device name of wlan0 or ra0 instead of wlp9s0. Run ip link to determine the correct device
name.
For most users, there are only two settings needed to connect, the ESSID (aka wireless network name) and, optionally, the WEP key.
First, ensure the interface is active:

root # ip link set dev wlp9s0 up
To connect to an open network with the name GentooNode:

root # iw dev wlp9s0 connect -w GentooNode
To connect with a hex WEP key, prefix the key with d: :

root # iw dev wlp9s0 connect -w GentooNode key 0:d:1234123412341234abcd
To connect with an ASCII WEP key:

root # iw dev wlp9s0 connect -w GentooNode key 0:some-password

Note
If the wireless network is set up with WPA or WPA2, then wpa_supplicant needs to be used. For more information on configuring
wireless networking in Gentoo Linux, please read the Wireless networking chapter in the Gentoo Handbook.
Confirm the wireless settings by using iw dev wlp9s0 link. Once wireless is working, continue configuring the IP level networking
options as described in the next section (Understanding network terminology) or use the net-setup tool as described previously.
Understanding network terminology


Note
If the IP address, broadcast address, netmask and nameservers are known, then skip this subsection and continue with Using
ifconfig and route.
If all of the above fails, the network will need to be configured manually. This is not difficult at all. However, some knowledge of network
terminology and basic concepts might be necessary. After reading this section, users will know what a gateway is, what a netmask
serves for, how a broadcast address is formed and why systems need nameservers.
In a network, hosts are identified by their IP address (Internet Protocol address). Such an address is perceived as a combination of four
numbers between 0 and 255. Well, at least when using IPv4 (IP version 4). In reality, such an IPv4 address consists of 32 bits (ones and
zeros). Let's view an example:
CODE Example of an IPv4 address
IP Address (numbers): 192.168.0.2

IP Address (bits): 11000000 10101000 00000000 00000010
-------- -------- -------- --------
192 168 0 2

Note
The successor of IPv4, IPv6, uses 128 bits (ones and zeros). In this section, the focus is on IPv4 addresses.
Such an IP address is unique to a host as far as all accessible networks are concerned (i.e. every host that one wants to be able to reach
must have a unique IP address). In order to distinguish between hosts inside and outside a network, the IP address is divided in two
parts: the network part and the host part.
The separation is written down with the netmask, a collection of ones followed by a collection of zeros. The part of the IP that can be
mapped on the ones is the network-part, the other one is the host-part. As usual, the netmask can be written down as an IP address.
CODE Example of network/host separation
IP address: 192 168 0 2

11000000 10101000 00000000 00000010
Netmask: 11111111 11111111 11111111 00000000
255 255 255 0
+--------------------------+--------+
Network Host
In other words, 192.168.0.14 is part of the example network, but 192.168.1.2 is not.
The broadcast address is an IP address with the same network-part as the network, but with only ones as host-part. Every host on the
network listens to this IP address. It is truly meant for broadcasting packets.
CODE Broadcast address
IP address: 192 168 0 2

11000000 10101000 00000000 00000010
Broadcast: 11000000 10101000 00000000 11111111
192 168 0 255
+--------------------------+--------+
Network Host
To be able to surf on the Internet, each computer in the network must know which host shares the Internet connection. This host is called
the gateway. Since it is a regular host, it has a regular IP address (for instance 192.168.0.1).
Previously we stated that every host has its own IP address. To be able to reach this host by a name (instead of an IP address) we need
a service that translates a name (such as dev.gentoo.org) to an IP address (such as 64.5.62.82). Such a service is called a name
service. To use such a service, the necessary name servers need to be defined in /etc/resolv.conf.
In some cases, the gateway also serves as a nameserver. Otherwise the nameservers provided by the ISP need to be entered in this
file.
To summarize, the following information is needed before continuing:
Network item Example
The system IP 192.168.0.2

address
Netmask 255.255.255.0
Broadcast 192.168.0.255
Gateway 192.168.0.1
Nameserver(s) 195.130.130.5, 195.130.130.133
Using ifconfig and route

Setting up the network consists of three steps:
1. Assign an IP address using ifconfig

2. Set up routing to the gateway using route
3. Finish up by placing the nameserver IPs in /etc/resolv.conf
To assign an IP address, the IP address, broadcast address and netmask are needed. Then execute the following command,
substituting ${IP_ADDR} with the right IP address, ${BROADCAST} with the right broadcast address and ${NETMASK} with the right
netmask:
root # ifconfig eth0 ${IP_ADDR} broadcast ${BROADCAST} netmask ${NETMASK} up
Set up routing using route. Substitute ${GATEWAY} with the right gateway IP address:
root # route add default gw ${GATEWAY}
Now open /etc/resolv.conf:
root # nano -w /etc/resolv.conf
Fill in the nameserver(s) using the following as a template. Make sure to substitute ${NAMESERVER1} and ${NAMESERVER2} with the
appropriate nameserver addresses:
FILE /etc/resolv.conf Default resolv.conf template
nameserver ${NAMESERVER1}
nameserver ${NAMESERVER2}
That's it. Now test the network by pinging some Internet server (like Google's 8.8.8.8 or Cloudflare's 1.1.1.1). If this works,
congratulations then. Continue with Preparing the disks.
Introduction to block devices

Block devices
Let's take a good look at disk-oriented aspects of Gentoo Linux and Linux in general, including Linux filesystems, partitions, and block
devices. Once the ins and outs of disks and filesystems are understood, partitions and filesystems can be established for the Gentoo
Linux installation.
To begin, let's look at block devices. The most famous block device is probably the one that represents the first drive in a Linux system,
namely /dev/sda. SCSI and Serial ATA drives are both labeled /dev/sd*; even IDE drives are labeled /dev/sd* with the libata
framework in the kernel. When using the old device framework, then the first IDE drive is /dev/hda.
The block devices above represent an abstract interface to the disk. User programs can use these block devices to interact with the disk
without worrying about whether the drives are IDE, SCSI, or something else. The program can simply address the storage on the disk as
a bunch of contiguous, randomly-accessible 512-byte blocks.
Partition tables
Although it is theoretically possible to use a raw, unpartitioned disk to house a Linux system (when creating a btrfs RAID for example),
this is almost never done in practice. Instead, disk block devices are split up into smaller, more manageable block devices. On amd64
systems, these are called partitions. There are currently two standard partitioning technologies in use: MBR and GPT.
MBR
The MBR (Master Boot Record) setup uses 32-bit identifiers for the start sector and length of the partitions, and supports three partition
types: primary, extended, and logical. Primary partitions have their information stored in the master boot record itself - a very small
(usually 512 bytes) location at the very beginning of a disk. Due to this small space, only four primary partitions are supported (for
instance, /dev/sda1 to /dev/sda4).
To support more partitions, one of the primary partitions can be marked as an extended partition. This partition can then contain logical
partitions (partitions within a partition).
 Important
Although still supported by most motherboard manufacturers partition tables are considered legacy. Unless working with hardware
that is pre-2010, it best to partition a disk using a GUID Partition Table. Readers who must proceed with MBR should acknowledge
the following information:
Most post-2010 motherboards consider MBR a legacy (supported, but not ideal) boot mode.
Due to using 32-bit identifiers, master boot record partitioning tables cannot handle disks that are greater than 2 TiBs in size.
Unless a extended partition is created, MBR supports a maximum of four partitions.
The MBR setup does not provide any backup-MBR, so if an application or user overwrites the MBR, all partition information is
lost.
The Handbook authors suggest using GPT whenever possible for Gentoo installations.
GPT
The GPT (GUID Partition Table) setup uses 64-bit identifiers for the partitions. The location in which it stores the partition information is
much bigger than the 512 bytes of an MBR, which means there is practically no limit on the amount of partitions for a GPT disk. Also the
size of a partition is bounded by a much greater limit (almost 8 ZiB - yes, zettabytes).
When a system's software interface between the operating system and firmware is UEFI (instead of BIOS), GPT is almost mandatory as
compatibility issues will arise with MBR.
GPT also takes advantage of checksumming and redundancy. It carries CRC32 checksums to detect errors in the header and partition
tables and has a backup GPT at the end of the disk. This backup table can be used to recover damage of the primary GPT near the
beginning of the disk.
GPT or MBR
From the description above, one might think that using GPT should always be the recommended approach, however there are a few
caveats.
Using GPT on a BIOS-based computer works, but then one cannot dual-boot with a Microsoft Windows operating system. The reason is
that Microsoft Windows will boot in UEFI mode if it detects a GPT partition label.
Some buggy motherboard firmware configured to boot in BIOS/CSM/legacy mode might also have problems with booting from GPT
labeled disks. If that is the case, it might be possible to work around the problem by adding the boot/active flag on the protective MBR
partition which has to be done through fdisk with the -t dos option to force it to read the partition table using the MBR format.
In this case, launch fdisk and toggle the flag using the a key. Press 1 to select the first partition, then press the w key to write the
changes to the disk and exit the fdisk application:
user $ fdisk -t dos /dev/sda

Welcome to fdisk (util-linux 2.24.1).
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.
Command (m for help): a

Partition number (1-4): 1
Command (m for help): w
Using UEFI
When installing Gentoo on a system that uses UEFI to boot the operating system (instead of BIOS), then it is important that an EFI
System Partition (ESP) is created. The instructions for parted below contain the necessary pointers to correctly handle this operation.
The ESP must be a FAT variant (sometimes shown as vfat on Linux systems). The official UEFI specification denotes FAT12, 16, or 32
filesystems will be recognized by the UEFI firmware, although FAT32 is recommended for the ESP. Proceed in formatting the ESP as
FAT32:
root # mkfs.fat -F 32 /dev/sda2

 Important
If a FAT variant is not used for the ESP, the system's UEFI firmware is not guaranteed to find the bootloader (or Linux kernel) and
most likely be unable to boot the system!
Advanced storage
Btrfs RAID
As noted above, btrfs has the ability to create filesystems across multiple devices. Btrfs filesystems generated in this way can act in the
following modes: raid0, raid1, raid10, raid5, and raid6. RAID modes 5 and 6 have improved considerably, but are still considered
unstable. After a multiple device filesystem has been created, new devices can be added and old devices removed in a few commands.
Btrfs takes more involvement than other filesystems making it not as friendly to beginners.
ext4 filesytems can be converted into btrfs filesystems, which may be useful for those who'd like to install Gentoo with a stable, well
tested filesystem and gradually increase their knowledge about newer filesystems such as btrfs by experimentation.
LVM
The amd64 Installation CDs provide support for Logical Volume Manager (LVM). LVM increases the flexibility offered by the partitioning
setup. The installation instructions below will focus on "regular" partitions, but it is good to know LVM is supported if that route is desired.
Visit the LVM article for more details. Newcomers beware: although fully supported LVM is outside the scope of this guide.
Default partitioning scheme

Throughout the remainder of the handbook, the following partitioning scheme will be used as a simple example layout:
Partition Filesystem Size Description
/dev/sda1 (bootloader) 2M BIOS boot partition
/dev/sda2 ext2 (or fat32 if UEFI is being used) 128M Boot/EFI system partition
/dev/sda3 (swap) 512M or higher Swap partition
/dev/sda4 ext4 Rest of the disk Root partition
If this suffices and the reader going the GPT route they can immediately jump to Default: Using parted to partition the disk. Those who
are still interested in MBR (hey - it happens!) and using the example layout can jump to Alternative: Using fdisk to partition the disk.
Both fdisk and parted are partitioning utilities. fdisk is well known, stable, and recommended for the MBR partition layout while
parted was one of the first Linux block device management utilities to support GPT partitions. Those who like the user interface of
fdisk can use gdisk (GPT fdisk) as an alternative to parted.
Before going to the creation instructions, the first set of sections will describe in more detail how partitioning schemes can be created and
mention some common pitfalls.
Designing a partition scheme

How many partitions and how big?
The number of partitions is highly dependent on the environment. For instance, if there are lots of users, then it is advised to have
/home/ separate as it increases security and makes backups easier. If Gentoo is being installed to perform as a mail server, then /var/
should be separate as all mails are stored inside /var/. A good choice of filesystem will then maximize the performance. Game servers
will have a separate /opt/ as most gaming servers are installed there. The reason is similar for the /home/ directory: security and
backups. In most situations, /usr/ is to be kept big: not only will it contain the majority of applications, it typically also hosts the Gentoo
ebuild repository (by default located at /usr/portage) which already takes around 650 MiB. This disk space estimate excludes the
packages/ and distfiles/ directories that are generally stored within this ebuild repository.
It very much depends on what the administrator wants to achieve. Separate partitions or volumes have the following advantages:
Choose the best performing filesystem for each partition or volume.

The entire system cannot run out of free space if one defunct tool is continuously writing files to a partition or volume.
If necessary, file system checks are reduced in time, as multiple checks can be done in parallel (although this advantage is more with
multiple disks than it is with multiple partitions).
Security can be enhanced by mounting some partitions or volumes read-only, nosuid (setuid bits are ignored), noexec
(executable bits are ignored) etc.
However, multiple partitions have disadvantages as well. If not configured properly, the system might have lots of free space on one
partition and none on another. Another nuisance is that separate partitions - especially for important mount points like /usr/ or /var/ -
often require the administrator to boot with an initramfs to mount the partition before other boot scripts start. This isn't always the case
though, so results may vary.
There is also a 15-partition limit for SCSI and SATA unless the disk uses GPT labels.
What about swap space?

There is no perfect value for the swap partition. The purpose of swap space is to provide disk storage to the kernel when internal
memory (RAM) is under pressure. A swap space allows for the kernel to move memory pages that are not likely to be accessed soon to
disk (swap or page-out), freeing memory. Of course, if that memory is suddenly needed, these pages need to be put back in memory
(page-in) which will take a while (as disks are very slow compared to internal memory).
When the system is not going to run memory intensive applications or the system has lots of memory available, then it probably does not
need much swap space. However, swap space is also used to store the entire memory in case of hibernation. If the system is going to
need hibernation, then a bigger swap space is necessary, often at least the amount of memory installed in the system.
What is the BIOS boot partition?

A BIOS boot partition is a very small (1 to 2 MB) partition in which boot loaders like GRUB2 can put additional data that doesn't fit in the
allocated storage (a few hundred bytes in case of MBR) and cannot be placed elsewhere.
Such partitions are not always necessary, but considering the low space consumption and the difficulties we have with documenting the
plethora of partitioning differences otherwise, it is recommended to create it in either case.
For completeness, the BIOS boot partition is needed when a GPT partition layout is used with GRUB2 in PC/BIOS mode. It is not
required when booting in EFI/UEFI mode.
Default: Using parted to partition the disk

In this chapter, the example partition layout mentioned earlier in the instructions will be used:
Partition Description
/dev/sda1 BIOS boot partition
/dev/sda2 Boot partition
/dev/sda3 Swap partition
/dev/sda4 Root partition
Change the partition layout according to personal preference.
Viewing the current partition layout with parted

The parted application offers a simple interface for partitioning the disks and supports very large partitions (more than 2 TB). Fire up
parted against the disk (in our example, we use /dev/sda). It is recommended to ask parted to use optimal partition alignment:
root # parted -a optimal /dev/sda

GNU Parted 2.3
Using /dev/sda
Welcome to GNU Parted! Type 'help' to view a list of commands.
Alignment means that partitions are started on well-known boundaries within the disk, ensuring that operations on the disk from the
operating system level (retrieve pages from the disk) use the least amount of internal disk operations. Misaligned partitions might require
the disk to fetch two pages instead of one even if the operating system asked for a single page.
To find out about all options supported by parted, type help and press return.
Setting the GPT label

Most disks on the x86 or amd64 architectures are prepared using an msdos label. Using parted, the command to put a GPT label on the
disk is mklabel gpt:
 Warning
Changing the partition type will remove all partitions from the disk. All data on the disk will be lost.
(parted) mklabel gpt

To have the disk with MBR layout, use mklabel msdos.
Removing all partitions with parted

If this isn't done yet (for instance through the mklabel operation earlier, or because the disk is a freshly formatted one), first remove all
existing partitions from the disk. Type print to view the current partitions, and rm <N> where <N> is the number of the partition to
remove.
(parted) rm 2
Do the same for all other partitions that aren't needed. However, make sure to not make any mistakes here - parted executes the
changes immediately (unlike fdisk which stages them, allowing a user to "undo" his changes before saving or exiting fdisk).
Creating the partitions

Now parted will be used to create the partitions with the following settings:
The partition type to use. This usually is primary. If the msdos partition label is used, keep in mind that there can be no more than 4
primary partitions. If more than 4 partitions are needed, make one of the first four partitions extended and create logical partitions
inside it.
The start location of a partition (which can be expressed in MB, GB, ...)
The end location of the partition (which can be expressed in MB, GB, ...)
First, tell parted that the size unit we work with is megabytes (actually mebibytes, abbreviated as MiB which is the "standard" notation,
but we will use MB in the text throughout as it is much more common):
(parted) unit mib
Now create a 2 MB partition that will be used by the GRUB2 boot loader later. Use the mkpart command for this, and inform parted to
start from 1 MB and end at 3 MB (creating a partition of 2 MB in size).
(parted) mkpart primary 1 3

(parted) name 1 grub
(parted) set 1 bios_grub on
(parted) print
Model: Virtio Block Device (virtblk)
Disk /dev/sda: 20480MiB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Number Start End Size File system Name Flags

1 1.00MiB 3.00MiB 2.00MiB grub bios_grub
Do the same for the boot partition (128 MB), swap partition (in the example, 512 MB) and the root partition that spans the remaining disk
(for which the end location is marked as -1, meaning the end of the disk minus one MB, which is the farthest a partition can go).

(parted) name 2 boot
(parted) name 3 swap
(parted) mkpart primary 643 -1
(parted) name 4 rootfs
When using the UEFI interface to boot the system (instead of BIOS), mark the boot partition as the EFI System Partition. Parted does this
automatically when the boot option is set on the partition:
(parted) set 2 boot on
The end result looks like so:

(parted) print
Model: Virtio Block Device (virtblk)
Disk /dev/sda: 20480MiB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Number Start End Size File system Name Flags

1 1.00MiB 3.00MiB 2.00MiB grub bios_grub
2 3.00MiB 131MiB 128MiB boot boot
3 131MiB 643MiB 512MiB swap
4 643MiB 20479MiB 19836MiB rootfs

Note
On an UEFI installation, the boot and esp flags will show up on the boot partition.
Use the quit command to exit parted.
Alternative: Using fdisk to partition the disk


Note
Although recent fdisk should support GPT, it has still shown to have some issues with it. The instructions given below assume that
the partition layout being used is MBR.
The following parts explain how to create the example partition layout using fdisk. The example partition layout was mentioned earlier:
Partition Description
/dev/sda1 BIOS boot partition
/dev/sda2 Boot partition
/dev/sda3 Swap partition
/dev/sda4 Root partition
Change the partition layout according to personal preference.
Viewing the current partition layout

fdisk is a popular and powerful tool to split a disk into partitions. Fire up fdisk against the disk (in our example, we use /dev/sda):
root # fdisk /dev/sda

Note
To use GPT support, add -t gpt . It is recommended to closely investigate the fdisk output in case more recent developments in
fdisk change its default behavior of defaulting to MBR. The remainder of the instructions assume an MBR layout.
Use the p key to display the disk's current partition configuration:
Command (m for help): p

Disk /dev/sda: 240 heads, 63 sectors, 2184 cylinders
Units = cylinders of 15120 * 512 bytes
Device Boot Start End Blocks Id System

/dev/sda1 * 1 14 105808+ 83 Linux
/dev/sda2 15 49 264600 82 Linux swap
/dev/sda3 50 70 158760 83 Linux
/dev/sda4 71 2184 15981840 5 Extended
/dev/sda5 71 209 1050808+ 83 Linux
/dev/sda6 210 348 1050808+ 83 Linux
/dev/sda7 349 626 2101648+ 83 Linux
/dev/sda8 627 904 2101648+ 83 Linux
/dev/sda9 905 2184 9676768+ 83 Linux
This particular disk was configured to house seven Linux filesystems (each with a corresponding partition listed as "Linux") as well as a
swap partition (listed as "Linux swap").
Removing all partitions with fdisk
First remove all existing partitions from the disk. Type d to delete a partition. For instance, to delete an existing /dev/sda1:
Command (m for help): d

The partition has now been scheduled for deletion. It will no longer show up when printing the list of partitions ( p , but it will not be
erased until the changes have been saved. This allows users to abort the operation if a mistake was made - in that case, type q
immediately and hit Enter and the partition will not be deleted.
Repeatedly type p to print out a partition listing and then type d and the number of the partition to delete it. Eventually, the partition
table will be empty:

Disk /dev/sda: 30.0 GB, 30005821440 bytes
240 heads, 63 sectors/track, 3876 cylinders
Units = cylinders of 15120 * 512 = 7741440 bytes
Now that the in-memory partition table is empty, we're ready to create the partitions.
Creating the BIOS boot partition

First create a very small BIOS boot partition. Type n to create a new partition, then p to select a primary partition, followed by 1 to
select the first primary partition. When prompted for the first sector, make sure it starts from 2048 (which is needed for the boot loader)
and hit Enter . When prompted for the last sector, type +2M to create a partition 2 Mbyte in size:

Note
The start from sector 2048 is a fail-safe in case the boot loader does not detect this partition as being available for its use.
Command (m for help): n

Command action
e extended
p primary partition (1-4)
p
First sector (64-10486533532, default 64): 2048
Last sector, +sectors +size{M,K,G} (4096-10486533532, default 10486533532): +2M
Mark the partition for UEFI purposes:
Command (m for help): t

Selected partition 1
Hex code (type L to list codes): 4
Changed system type of partition 1 to 4 (BIOS boot)

Note
Using UEFI with MBR partition layout is discouraged. If an UEFI capable system is used, please use GPT layout.
Creating the boot partition

Now create a small boot partition. Type n to create a new partition, then p to select a primary partition, followed by 2 to select the
second primary partition. When prompted for the first sector, accept the default by hitting Enter . When prompted for the last sector,
type +128M to create a partition 128 Mbyte in size:
Command (m for help): n

Command action
e extended
p primary partition (1-4)
p
First sector (5198-10486533532, default 5198): (Hit enter)
Last sector, +sectors +size{M,K,G} (4096-10486533532, default 10486533532): +128M
Now, when pressing p , the following partition printout is displayed:


/dev/sda1 1 3 5198+ ef EFI (FAT-12/16/32)
/dev/sda2 3 14 105808+ 83 Linux
Type a to toggle the bootable flag on a partition and select 2 . After pressing p again, notice that an * is placed in the "Boot" column.
Creating the swap partition

To create the swap partition, type n to create a new partition, then p to tell fdisk to create a primary partition. Then type 3 to create
the third primary partition, /dev/sda3. When prompted for the first sector, hit Enter . When prompted for the last sector, type +512M
(or any other size needed for the swap space) to create a partition 512MB in size.
After all this is done, type t to set the partition type, 3 to select the partition just created and then type in 82 to set the partition type to
"Linux Swap".
Creating the root partition

Finally, to create the root partition, type n to create a new partition, then p to tell fdisk to create a primary partition. Then type 4 to
create the fourth primary partition, /dev/sda4. When prompted for the first sector, hit Enter . When prompted for the last sector, hit
Enter to create a partition that takes up the rest of the remaining space on the disk. After completing these steps, typing p should
display a partition table that looks similar to this:


/dev/sda1 1 3 5198+ ef EFI (FAT-12/16/32)
/dev/sda2 * 3 14 105808+ 83 Linux
/dev/sda3 15 81 506520 82 Linux swap
/dev/sda4 82 3876 28690200 83 Linux
Saving the partition layout

To save the partition layout and exit fdisk, type w .
Command (m for help): w
With the partitions created, it is now time to put filesystems on them.
Creating file systems

Introduction
Now that the partitions are created, it is time to place a filesystem on them. In the next section the various file systems that Linux
supports are described. Readers that already know which filesystem to use can continue with Applying a filesystem to a partition. The
others should read on to learn about the available filesystems...
Filesystems
Several filesystems are available. Some of them are found stable on the amd64 architecture - it is advised to read up on the filesystems
and their support state before selecting a more experimental one for important partitions.
btrfs
A next generation filesystem that provides many advanced features such as snapshotting, self-healing through checksums,
transparent compression, subvolumes and integrated RAID. A few distributions have begun to ship it as an out-of-the-box option, but
it is not production ready. Reports of filesystem corruption are common. Its developers urge people to run the latest kernel version for
safety because the older ones have known problems. This has been the case for years and it is too early to tell if things have
changed. Fixes for corruption issues are rarely backported to older kernels. Proceed with caution when using this filesystem!
ext2
This is the tried and true Linux filesystem but doesn't have metadata journaling, which means that routine ext2 filesystem checks at
startup time can be quite time-consuming. There is now quite a selection of newer-generation journaled filesystems that can be
checked for consistency very quickly and are thus generally preferred over their non-journaled counterparts. Journaled filesystems
prevent long delays when the system is booted and the filesystem happens to be in an inconsistent state.
ext3
The journaled version of the ext2 filesystem, providing metadata journaling for fast recovery in addition to other enhanced journaling
modes like full data and ordered data journaling. It uses an HTree index that enables high performance in almost all situations. In
short, ext3 is a very good and reliable filesystem.
ext4
Initially created as a fork of ext3, ext4 brings new features, performance improvements, and removal of size limits with moderate
changes to the on-disk format. It can span volumes up to 1 EB and with maximum file size of 16TB. Instead of the classic ext2/3
bitmap block allocation ext4 uses extents, which improve large file performance and reduce fragmentation. Ext4 also provides more
sophisticated block allocation algorithms (delayed allocation and multiblock allocation) giving the filesystem driver more ways to
optimize the layout of data on the disk. Ext4 is the recommended all-purpose all-platform filesystem.
f2fs
The Flash-Friendly File System was originally created by Samsung for the use with NAND flash memory. As of Q2, 2016, this
filesystem is still considered immature, but it is a decent choice when installing Gentoo to microSD cards, USB drives, or other flash-
based storage devices.
JFS
IBM's high-performance journaling filesystem. JFS is a light, fast and reliable B+tree-based filesystem with good performance in
various conditions.
ReiserFS
A B+tree-based journaled filesystem that has good overall performance, especially when dealing with many tiny files at the cost of
more CPU cycles. ReiserFS appears to be less maintained than other filesystems.
XFS
A filesystem with metadata journaling which comes with a robust feature-set and is optimized for scalability. XFS seems to be less
forgiving to various hardware problems.
vfat
Also known as FAT32, is supported by Linux but does not support any permission settings. It is mostly used for interoperability with
other operating systems (mainly Microsoft Windows) but is also a necessity for some system firmware (like UEFI).
NTFS
This "New Technology" filesystem is the flagship filesystem of Microsoft Windows. Similar to vfat above it does not store permission
settings or extended attributes necessary for BSD or Linux to function properly, therefore it cannot be used as a root filesystem. It
should only be used for interoperability with Microsoft Windows systems (note the emphasis on only).
When using ext2, ext3, or ext4 on a small partition (less than 8GB), then the file system must be created with the proper options to
reserve enough inodes. The mke2fs (mkfs.ext2) application uses the "bytes-per-inode" setting to calculate how many inodes a file
system should have. On smaller partitions, it is advised to increase the calculated number of inodes.
On ext2, ext3 and ext4, this can be done using one of the following commands, respectively:
root # mkfs.ext2 -T small /dev/<device>

This will generally quadruple the number of inodes for a given file system as its "bytes-per-inode" reduces from one every 16kB to one
every 4kB. This can be tuned even further by providing the ratio:
root # mkfs.ext2 -i <ratio> /dev/<device>
Applying a filesystem to a partition

To create a filesystem on a partition or volume, there are user space utilities available for each possible filesystem. Click the filesystem's
name in the table below for additional information on each filesystem:
Filesystem Creation command On minimal CD? Package
btrfs mkfs.btrfs  Yes sys-fs/btrfs-progs
ext2 mkfs.ext2  Yes sys-fs/e2fsprogs
f2fs mkfs.f2fs  Yes sys-fs/f2fs-tools
jfs mkfs.jfs  Yes sys-fs/jfsutils

reiserfs mkfs.reiserfs  Yes sys-fs/reiserfsprogs
xfs mkfs.xfs  Yes sys-fs/xfsprogs
vfat mkfs.vfat  Yes sys-fs/dosfstools
NTFS mkfs.ntfs  Yes sys-fs/ntfs3g
For instance, to have the boot partition (/dev/sda2) in ext2 and the root partition (/dev/sda4) in ext4 as used in the example partition
structure, the following commands would be used:
root # mkfs.ext2 /dev/sda2
root # mkfs.ext4 /dev/sda4
Now create the filesystems on the newly created partitions (or logical volumes).
Activating the swap partition

mkswap is the command that is used to initialize swap partitions:
root # mkswap /dev/sda3
To activate the swap partition, use swapon:
root # swapon /dev/sda3
Create and activate the swap with the commands mentioned above.
Mounting the root partition

Now that the partitions are initialized and are housing a filesystem, it is time to mount those partitions. Use the mount command, but
don't forget to create the necessary mount directories for every partition created. As an example we mount the root partition:
root # mount /dev/sda4 /mnt/gentoo

Note
If /tmp/ needs to reside on a separate partition, be sure to change its permissions after mounting:
root # chmod 1777 /mnt/gentoo/tmp
This also holds for /var/tmp.
Later in the instructions the proc filesystem (a virtual interface with the kernel) as well as other kernel pseudo-filesystems will be
mounted. But first we install the Gentoo installation files.
Installing a stage tarball

Setting the date and time
Before installing Gentoo, it is a good idea to be sure the date and time are set correctly. A mis-configured clock may lead to strange
results: base system files should be extracted with accurate time stamps. In fact, due to several websites and services using encrypted
communications (SSL/TLS), it might not be possible to download the installation files at all if the system clock is too far skewed!
Verify the current date and time by running the date command:
root # date
Mon Oct 3 13:16:22 PDT 2016
If the date/time displayed is wrong, update it using one of the methods below.

Note
Motherboards that do not include a Real-Time Clock (RTC) should be configured to automatically sync the system clock with a time
server. This is also true for systems that do include a RTC, but have a failed battery.
Automatic
Official Gentoo installation media includes the ntpd command (available through the net-misc/ntp package). Official media includes a
configuration file pointing to ntp.org time servers. It can be used to automatically sync the system clock to UTC time using a time server.
Using this method requires a working network configuration and may not be available on all architectures.
 Warning
Automatic time sync comes at a price. It will reveal the system's IP address and related network information to a time server (in the
case of the example below ntp.org). Users with privacy concerns should be aware of this before setting the system clock using the
below method.
root # ntpd -q -g
Manual
The date command can also be used to perform a manual set on the system clock. Use the MMDDhhmmYYYY syntax (Month, Day, hour,
minute and Year).
UTC time is recommended for all Linux systems. Later on during the installation a timezone will be defined. This will modify the display of
the clock to local time.
For instance, to set the date to October 3rd, 13:16 in the year 2016:
root # date 100313162016
Choosing a stage tarball

Multilib (32 and 64-bit)
Choosing a base tarball for the system can save a considerable amount of time later on in the installation process, specifically when it is
time to choose a system profile. The selection of a stage tarball will directly impact future system configuration and can save a headache
or two later on down the line. The multilib tarball uses 64-bit libraries when possible, and only falls back to the 32-bit versions when
necessary for compatibility. This is an excellent option for the majority of installations because it provides a great amount of flexibility for
customization in the future. Those who desire their systems to be capable of easily switching profiles should download the multilib tarball
option for their respective processor architecture.
Most users should not use the 'advanced' tarballs options; they are for specific software or hardware configurations.
No-multilib (pure 64-bit)

Selecting a no-multilib tarball to be the base of the system provides a complete 64-bit operating system environment. This effectively
renders the ability to switch to multilib profiles improbable, but possible. Those who are just starting out with Gentoo should not
choose a no-multilib tarball unless it is absolutely necessary.
 Warning
Be aware, migrating from a no-multilib to a multilib system requires an extremely well-working knowledge of Gentoo and the lower-
level toolchain (it may even cause our Toolchain developers to shudder a little). It is not for the faint of heart and is beyond the
scope of this guide.
Downloading the stage tarball

Go to the Gentoo mount point where the root file system is mounted (most likely /mnt/gentoo):
root # cd /mnt/gentoo
Depending on the installation medium, the only tool necessary to download a stage tarball is a web browser.
Graphical browsers
Those using environments with fully graphical web browsers will have no problem copying a stage file URL from the main website's
download section . Simply select the appropriate tab, right click the link to the stage file, then Copy link address (Firefox) or Copy
link location (Chromium) to copy the link to the clipboard, then paste the link to the wget utility on the command-line to download the
stage tarball:
root # wget <PASTED_STAGE_URL>

Command-line browsers
More traditional readers or 'old timer' Gentoo users, working exclusively from command-line may prefer using links, a non-graphical,
menu-driven browser. To download a stage, surf to the Gentoo mirror list like so:
root # links https://www.gentoo.org/downloads/mirrors/
To use an HTTP proxy with links, pass on the URL with the -http-proxy option:
root # links -http-proxy proxy.server.com:8080 https://www.gentoo.org/downloads/mirrors/
Next to links there is also the lynx browser. Like links it is a non-graphical browser but it is not menu-driven.
root # lynx https://www.gentoo.org/downloads/mirrors/
If a proxy needs to be defined, export the http_proxy and/or ftp_proxy variables:
root # export http_proxy="http://proxy.server.com:port"

root # export ftp_proxy="http://proxy.server.com:port"
On the mirror list, select a mirror close by. Usually HTTP mirrors suffice, but other protocols are available as well. Move to the
releases/amd64/autobuilds/ directory. There all available stage files are displayed (they might be stored within subdirectories
named after the individual sub-architectures). Select one and press d to download.
After the stage file download completes, it is possible to verify the integrity and validate the contents of the stage tarball. Those interested
should proceed to the next section.
Those not interested in verifying and validating the stage file can close the command-line browser by pressing q and can move directly
to the Unpacking the stage tarball section.
Verifying and validating


Note
Some tarballs are being delivered via xz compression. When downloading a tarball ending in .tar.xz, be sure to adjust the tarball
filename from .tar.bz2 in the following commands.
Like with the minimal installation CDs, additional downloads to verify and validate the stage file are available. Although these steps may
be skipped, these files are provided for users who care about the legitimacy of the file(s) they just downloaded.
A .CONTENTS file that contains a list of all files inside the stage tarball.
A .DIGESTS file that contains checksums of the stage file in different algorithms.
A .DIGESTS.asc file that, like the .DIGESTS file, contains checksums of the stage file in different algorithms, but is also
cryptographically signed to ensure it is provided by the Gentoo project.
Use openssl and compare the output with the checksums provided by the .DIGESTS or .DIGESTS.asc files.
For instance, to validate the SHA512 checksum:
root # openssl dgst -r -sha512 stage3-amd64-<release>.tar.?(bz2|xz)
Another way is to use the sha512sum command:
root # sha512sum stage3-amd64-<release>.tar.?(bz2|xz)
To validate the Whirlpool checksum:
root # openssl dgst -r -whirlpool stage3-amd64-<release>.tar.?(bz2|xz)
Compare the output of these commands with the value registered in the .DIGESTS(.asc) files. The values need to match, otherwise the
downloaded file might be corrupt (or the digests file is).
Just like with the ISO file, it is also possible to verify the cryptographic signature of the .DIGESTS.asc file using gpg to make sure the
checksums have not been tampered with:
root # gpg --verify stage3-amd64-<release>.tar.?(bz2|xz){.DIGESTS.asc,}
Unpacking the stage tarball

Now unpack the downloaded stage onto the system. We use tar to proceed:
root # tar xpvf stage3-*.tar.bz2 --xattrs-include='*.*' --numeric-owner
Make sure that the same options ( xpf and --xattrs-include='*.*' ) are used. The x stands for extract, the p for preserve
permissions and the f to denote that we want to extract a file (not standard input). --xattrs-include='*.*' is to include
preservation of the the extended attributes in all namespaces stored in the archive. Finally, --numeric-owner is used to ensure that
the user and group IDs of the files being extracted from the tarball will remain the same as Gentoo's release engineering team intended
(even if adventurous users are not using official Gentoo installation media).
Now that the stage file is unpacked, proceed with Configuring the compile options.
Configuring compile options

Introduction
To optimize Gentoo, it is possible to set a couple of variables which impacts the behavior of Portage, Gentoo's officially supported
package manager. All those variables can be set as environment variables (using export) but that isn't permanent. To keep the settings,
Portage reads in the /etc/portage/make.conf file, a configuration file for Portage.

Note
A commented listing of all possible variables can be found in /mnt/gentoo/usr/share/portage/config/make.conf.example.
For a successful Gentoo installation only the variables that are mentioned below need to be set.
Fire up an editor (in this guide we use nano) to alter the optimization variables we will discuss hereafter.
root # nano -w /mnt/gentoo/etc/portage/make.conf
From the make.conf.example file it is obvious how the file should be structured: commented lines start with "#", other lines define
variables using the VARIABLE="content" syntax. Several of those variables are discussed next.
CFLAGS and CXXFLAGS

The CFLAGS and CXXFLAGS variables define the optimization flags for GCC C and C++ compilers respectively. Although those are
defined generally here, for maximum performance one would need to optimize these flags for each program separately. The reason for
this is because every program is different. However, this is not manageable, hence the definition of these flags in the make.conf file.
In make.conf one should define the optimization flags that will make the system the most responsive generally. Don't place experimental
settings in this variable; too much optimization can make programs behave bad (crash, or even worse, malfunction).
We will not explain all possible optimization options. To understand them all, read the GNU Online Manual(s) or the gcc info page
(info gcc - only works on a working Linux system). The make.conf.example file itself also contains lots of examples and information;
don't forget to read it too.
A first setting is the -march= or -mtune= flag, which specifies the name of the target architecture. Possible options are described in
the make.conf.example file (as comments). A commonly used value is native as that tells the compiler to select the target architecture
of the current system (the one users are installing Gentoo on).
A second one is the -O flag (that is a capital O, not a zero), which specifies the gcc optimization class flag. Possible classes are s (for
size-optimized), 0 (zero - for no optimizations), 1, 2 or even 3 for more speed-optimization flags (every class has the same flags as the
one before, plus some extras). -O2 is the recommended default. -O3 is known to cause problems when used system-wide, so we
recommend to stick to -O2 .
Another popular optimization flag is -pipe (use pipes rather than temporary files for communication between the various stages of
compilation). It has no impact on the generated code, but uses more memory. On systems with low memory, gcc might get killed. In that
case, do not use this flag.
Using -fomit-frame-pointer (which doesn't keep the frame pointer in a register for functions that don't need one) might have
serious repercussions on the debugging of applications.
When the CFLAGS and CXXFLAGS variables are defined, combine the several optimization flags in one string. The default values
contained in the stage3 archive that is unpacked should be good enough. The following one is just an example:
CODE Example CFLAGS and CXXFLAGS variables
# Compiler flags to set for all languages

COMMON_FLAGS="-march=native -O2 -pipe"
# Use the same settings for both variables
CFLAGS="${COMMON_FLAGS}"
CXXFLAGS="${COMMON_FLAGS}"
 Tip
Although the GCC optimization article has more information on how the various compilation options can affect a system, the Safe
CFLAGS article may be a more practical place for beginners to start optimizing their systems.
MAKEOPTS
The MAKEOPTS variable defines how many parallel compilations should occur when installing a package. A good choice is the number
of CPUs (or CPU cores) in the system plus one, but this guideline isn't always perfect.
CODE Example MAKEOPTS declaration in make.conf
MAKEOPTS="-j2"
Ready, set, go!

Update the /mnt/gentoo/etc/portage/make.conf file to match personal preference and save (nano users would hit Ctrl + X ).
Then continue with Installing the Gentoo base system.
Chrooting
Optional: Selecting mirrors
Distribution files
In order to download source code quickly it is recommended to select a fast mirror. Portage will look in the make.conf file for the
GENTOO_MIRRORS variable and use the mirrors listed therein. It is possible to surf to the Gentoo mirror list and search for a mirror (or
mirrors) that is close to the system's physical location (as those are most frequently the fastest ones). However, we provide a nice tool
called mirrorselect which provides users with a nice interface to select the mirrors needed. Just navigate to the mirrors of choice and
press Spacebar to select one or more mirrors.
root # mirrorselect -i -o >> /mnt/gentoo/etc/portage/make.conf
Gentoo ebuild repository

A second important step in selecting mirrors is to configure the Gentoo ebuild repository via the
/etc/portage/repos.conf/gentoo.conf file. This file contains the sync information needed to update the package repository (the
collection of ebuilds and related files containing all the information Portage needs to download and install software packages).
Configuring the repository can be done in a few simple steps. First, if it does not exist, create the repos.conf directory:
root # mkdir --parents /mnt/gentoo/etc/portage/repos.conf
Next, copy the Gentoo repository configuration file provided by Portage to the (newly created) repos.conf directory:
root # cp /mnt/gentoo/usr/share/portage/config/repos.conf /mnt/gentoo/etc/portage/repos.conf/gentoo.conf
Take a peek with a text editor or by using the cat command. The inside of the file should be in .ini format and look like this:
FILE /mnt/gentoo/etc/portage/repos.conf/gentoo.conf
[DEFAULT]
main-repo = gentoo
[gentoo]
location = /usr/portage
sync-type = rsync
sync-uri = rsync://rsync.gentoo.org/gentoo-portage
auto-sync = yes
sync-rsync-verify-jobs = 1
sync-rsync-verify-metamanifest = yes
sync-rsync-verify-max-age = 24
sync-openpgp-key-path = /usr/share/openpgp-keys/gentoo-release.asc
sync-openpgp-key-refresh-retry-count = 40
sync-openpgp-key-refresh-retry-overall-timeout = 1200
sync-openpgp-key-refresh-retry-delay-exp-base = 2
sync-openpgp-key-refresh-retry-delay-max = 60
sync-openpgp-key-refresh-retry-delay-mult = 4
The default sync-uri variable value listed above will determine a mirror location based on a rotation. This will aid in easing bandwidth
stress on Gentoo's infrastructure and will provide a fail-safe in case a specific mirror is offline. It is recommended the default URI is
retained unless a local, private Portage mirror will be used.
 Tip
For those interested, the official specification for Portage's plug-in sync API can be found in the Portage project's Sync article.
Copy DNS info

One thing still remains to be done before entering the new environment and that is copying over the DNS information in
/etc/resolv.conf. This needs to be done to ensure that networking still works even after entering the new environment.
/etc/resolv.conf contains the name servers for the network.
To copy this information, it is recommended to pass the --dereference option to the cp command. This ensures that, if
/etc/resolv.conf is a symbolic link, that the link's target file is copied instead of the symbolic link itself. Otherwise in the new
environment the symbolic link would point to a non-existing file (as the link's target is most likely not available inside the new
environment).
root # cp --dereference /etc/resolv.conf /mnt/gentoo/etc/
Mounting the necessary filesystems

In a few moments, the Linux root will be changed towards the new location. To make sure that the new environment works properly,
certain filesystems need to be made available there as well.
The filesystems that need to be made available are:
/proc/ which is a pseudo-filesystem (it looks like regular files, but is actually generated on-the-fly) from which the Linux kernel
exposes information to the environment
/sys/ which is a pseudo-filesystem, like /proc/ which it was once meant to replace, and is more structured than /proc/
/dev/ is a regular file system, partially managed by the Linux device manager (usually udev), which contains all device files
The /proc/ location will be mounted on /mnt/gentoo/proc/ whereas the other two are bind-mounted. The latter means that, for
instance, /mnt/gentoo/sys/ will actually be /sys/ (it is just a second entry point to the same filesystem) whereas /mnt/gentoo/proc/
is a new mount (instance so to speak) of the filesystem.
root # mount --types proc /proc /mnt/gentoo/proc

root # mount --rbind /sys /mnt/gentoo/sys
root # mount --make-rslave /mnt/gentoo/sys
root # mount --rbind /dev /mnt/gentoo/dev
root # mount --make-rslave /mnt/gentoo/dev

Note
The --make-rslave operations are needed for systemd support later in the installation.
 Warning
When using non-Gentoo installation media, this might not be sufficient. Some distributions make /dev/shm a symbolic link to
/run/shm/ which, after the chroot, becomes invalid. Making /dev/shm/ a proper tmpfs mount up front can fix this:
root # test -L /dev/shm && rm /dev/shm && mkdir /dev/shm
root # mount --types tmpfs --options nosuid,nodev,noexec shm /dev/shm
Also ensure that mode 1777 is set:

root # chmod 1777 /dev/shm
Entering the new environment

Now that all partitions are initialized and the base environment installed, it is time to enter the new installation environment by chrooting
into it. This means that the session will change its root (most top-level location that can be accessed) from the current installation
environment (installation CD or other installation medium) to the installation system (namely the initialized partitions). Hence the name,
change root or chroot.
This chrooting is done in three steps:
1. The root location is changed from / (on the installation medium) to /mnt/gentoo/ (on the partitions) using chroot
2. Some settings (those in /etc/profile) are reloaded in memory using the source command
3. The primary prompt is changed to help us remember that this session is inside a chroot environment.
root # chroot /mnt/gentoo /bin/bash
root # source /etc/profile
root # export PS1="(chroot) ${PS1}"
From this point, all actions performed are immediately on the new Gentoo Linux environment. Of course it is far from finished, which is
why the installation still has some sections left!
 Tip
If the Gentoo installation is interrupted anywhere after this point, it should be possible to 'resume' the installation at this step. There
is no need to repartition the disks again! Simply mount the root partition and run the steps above starting with copying the DNS info
to re-enter the working environment. This is also useful for fixing bootloader issues. More information can be found in the chroot
article.
Mounting the boot partition

Now that the new environment has been entered, it is necessary to create and mount the /boot partition. This will be important when it
is time to compile the kernel and install the bootloader:
root # mkdir /boot

root # mount /dev/sda2 /boot
Configuring Portage
Installing an ebuild repository snapshot from the web
Next step is to install a snapshot of the main ebuild repository. This snapshot contains a collection of files that informs Portage about
available software titles (for installation), which profiles the system administrator can select, package or profile specific news items, etc.
The use of emerge-webrsync is recommended for those who are behind restrictive firewalls (because it uses HTTP/FTP protocols for
downloading the snapshot) and saves network bandwidth. Readers who have no network or bandwidth restrictions can happily skip down
to the next section.
This will fetch the latest snapshot (which is released on a daily basis) from one of Gentoo's mirrors and install it onto the system:
root # emerge-webrsync

Note
During this operation, emerge-webrsync might complain about a missing /usr/portage/ location. This is to be expected and
nothing to worry about - the tool will create the location.
From this point onward, Portage might mention that certain updates are recommended to be executed. This is because system
packages installed through the stage file might have newer versions available; Portage is now aware of new packages because of the
repository snapshot. Package updates can be safely ignored for now; updates can be delayed after the Gentoo installation has finished.
Optional: Updating the Gentoo ebuild repository
It is possible to update the Gentoo ebuild repository to the latest version. The previous emerge-webrsync command will have installed a
very recent snapshot (usually recent up to 24h) so this step is definitely optional.
Suppose there is a need for the last package updates (up to 1 hour), then use emerge --sync. This command will use the rsync
protocol to update the Gentoo ebuild repository (which was fetched earlier on through emerge-webrsync) to the latest state.
root # emerge --sync
On slow terminals, like some framebuffers or serial consoles, it is recommended to use the --quiet option to speed up the process:
root # emerge --sync --quiet
Reading news items

When the Gentoo ebuild repository is synchronized to the system, Portage may warn the user with messages similar to the following:
* IMPORTANT: 2 news items need reading for repository 'gentoo'.

* Use eselect news to read news items.
News items were created to provide a communication medium to push critical messages to users via the rsync tree. To manage them,
use eselect news. The eselect application is a Gentoo application that allows for a common management interface towards system
changes and operations. In this case, eselect is asked to use its news module.
For the news module, three operations are most used:
With list an overview of the available news items is displayed.

With read the news items can be read.
With purge news items can be removed once they have been read and will not be reread anymore.
root # eselect news list
root # eselect news read
More information about the newsreader is available through its manual page:
root # man news.eselect
Choosing the right profile

 Warning
Do not select any of the the 17.1 profiles until reading the corresponding 17.1 news item . This profile is experimental and requires
special migration instructions.
A profile is a building block for any Gentoo system. Not only does it specify default values for USE, CFLAGS, and other important
variables, it also locks the system to a certain range of package versions. These settings are all maintained by Gentoo's Portage
developers.
You can see what profile the system is currently using with eselect, now using the profile module:
root # eselect profile list

Available profile symlink targets:
[1] default/linux/amd64/13.0 *
[2] default/linux/amd64/13.0/desktop
[3] default/linux/amd64/13.0/desktop/gnome
[4] default/linux/amd64/13.0/desktop/kde

Note
The output of the command is just an example and evolves over time.
As can be seen, there are also desktop subprofiles available for some architectures.
 Warning
Profile upgrades are not to be taken lightly. When selecting the initial profile, make sure to use profile corresponding to the same
version as the one initially used by stage3 (e.g. 13.0). Each new profile version is announced through a news item containing
migration instructions. Make sure to read it and follow them before switching to a newer profile.
After viewing the available profiles for the amd64 architecture, users can select a different profile for the system:
root # eselect profile set 2
No-multilib
In order to select a pure 64-bit environment, with no 32-bit applications or libraries, use a no-multilib profile:

[1] default/linux/amd64/13.0 *
[5] default/linux/amd64/13.0/no-multilib
Next select the no-multilib profile:
root # eselect profile set 5

[1] default/linux/amd64/13.0
[5] default/linux/amd64/13.0/no-multilib *
systemd
Those who desire systemd as their init system should select a profile with systemd somewhere in the profile name:
root # eselect profile set default/linux/amd64/13.0/systemd

[10] default/linux/amd64/13.0/developer
[11] default/linux/amd64/13.0/no-multilib
[12] default/linux/amd64/13.0/systemd *
[13] default/linux/amd64/13.0/x32
[14] hardened/linux/amd64
 Tip
As seen above, full profile names can be used instead of the profile's associated numerical value.

Note
The developer subprofile is specifically for Gentoo Linux development and is not meant to be used by casual users.
Updating the @world set

At this point, it is wise to update the system's @world set so that a base can be established.
This following step is necessary so the system can apply any updates or USE flag changes which have appeared since the stage3 was
built and from any profile selection:
root # emerge --ask --verbose --update --deep --newuse @world
 Tip
If a full scale desktop environment profile has been selected this process could greatly extend the amount of time necessary for the
install process. Those in a time crunch can work by this 'rule of thumb': the shorter the profile name, the less specific the system's
@world set; the less specific the @world set, the fewer packages the system will require. In other words:
selecting default/linux/amd64/13.0 will require very few packages to be updated, whereas
selecting default/linux/amd64/13.0/desktop/gnome/systemd will require many packages to be installed since the init
system is changing from OpenRC to systemd, and the GNOME desktop environment framework will be installed.
Configuring the USE variable

USE is one of the most powerful variables Gentoo provides to its users. Several programs can be compiled with or without optional
support for certain items. For instance, some programs can be compiled with support for GTK+ or with support for Qt. Others can be
compiled with or without SSL support. Some programs can even be compiled with framebuffer support (svgalib) instead of X11 support
(X-server).
Most distributions compile their packages with support for as much as possible, increasing the size of the programs and startup time, not
to mention an enormous amount of dependencies. With Gentoo users can define what options a package should be compiled with. This
is where USE comes into play.
In the USE variable users define keywords which are mapped onto compile-options. For instance, ssl will compile SSL support in the
programs that support it. -X will remove X-server support (note the minus sign in front). gnome gtk -kde -qt4 -qt5 will compile
programs with GNOME (and GTK+) support, and not with KDE (and Qt) support, making the system fully tweaked for GNOME (if the
architecture supports it).
The default USE settings are placed in the make.defaults files of the Gentoo profile used by the system. Gentoo uses a (complex)
inheritance system for its profiles, which we will not dive into at this stage. The easiest way to check the currently active USE settings is to
run emerge --info and select the line that starts with USE:
root # emerge --info | grep ^USE

USE="X acl alsa amd64 berkdb bindist bzip2 cli cracklib crypt cxx dri ..."

Note
The above example is truncated, the actual list of USE values is much, much larger.
A full description on the available USE flags can be found on the system in /usr/portage/profiles/use.desc.
root # less /usr/portage/profiles/use.desc
Inside the less command, scrolling can be done using the ↑ and ↓ keys, and exited by pressing q .
As an example we show a USE setting for a KDE-based system with DVD, ALSA, and CD recording support:
root # nano -w /etc/portage/make.conf
FILE /etc/portage/make.conf Enabling USE for a KDE-based system with DVD, ALSA and CD recording support
USE="-gtk -gnome qt4 qt5 kde dvd alsa cdr"
When USE is defined in /etc/portage/make.conf it is added (or removed if the USE flag starts with the - sign) from that default list.
Users who want to ignore any default USE settings and manage it completely themselves should start the USE definition in make.conf
with -* :
FILE /etc/portage/make.conf Ignoring default USE flags
USE="-* X acl alsa"
 Warning
Although possible, setting -* (as seen in the example above) is discouraged as carefully chosen USE flag defaults may be
configured in some ebuilds to prevent conflicts and other errors.
Optional: Configuring the ACCEPT_LICENSE variable

All of the Gentoo packages are tagged with the license(s) the package falls under. This allows users to select software by specific
licenses or groups of licenses prior to installing it.
Portage uses the ACCEPT_LICENSE variable to determine which packages to allow without prompting the user for the licenses
previously accepted. Exceptions can be made per-package in /etc/portage/package.license as well.
The license groups defined in the Gentoo repository, managed by the Gentoo Licenses project, are:
Group Name Description

@GPL-COMPATIBLE GPL compatible licenses approved by the Free Software Foundation [a_license 1]
@FSF-APPROVED Free software licenses approved by the FSF (includes @GPL-COMPATIBLE)

@OSI-APPROVED Licenses approved by the Open Source Initiative [a_license 2]
Misc licenses that are probably free software, i.e. follow the Free Software Definition [a_license 3] but are not
@MISC-FREE
approved by either FSF or OSI
@FREE-SOFTWARE Combines @FSF-APPROVED, @OSI-APPROVED and @MISC-FREE
@FSF-APPROVED- FSF-approved licenses for "free documentation" and "works of practical use besides software and
OTHER documentation" (including fonts)
Misc licenses for free documents and other works (including fonts) that follow the free definition [a_license 4] but
@MISC-FREE-DOCS
are NOT listed in @FSF-APPROVED-OTHER
@FREE-
Combines @FSF-APPROVED-OTHER and @MISC-FREE-DOCS
DOCUMENTS
@FREE Combines @FREE-SOFTWARE and @FREE-DOCUMENTS
@BINARY- Includes @FREE and other freely distributable closed source software which do not have an End-User License
REDISTRIBUTABLE Agreement (EULA)
License agreements that try to take away your rights. These are more restrictive than "all-rights-reserved" or
@EULA
require explicit approval
1. ↑ https://www.gnu.org/licenses/license-list.html
2. ↑ https://www.opensource.org/licenses
3. ↑ https://www.gnu.org/philosophy/free-sw.html
4. ↑ https://freedomdefined.org/
Gentoo comes with a predefined value in the profiles, for example:
user $ portageq envvar ACCEPT_LICENSE

* -@EULA
This can be customized system wide by changing /etc/portage/make.conf to, e.g. only accept FSF and OSI, and similar, "Free"
software:
FILE /etc/portage/make.conf Customizing ACCEPT_LICENSE
ACCEPT_LICENSE="-* @FREE"
Per package overrides can then be added if necessary and desired, for example:
FILE /etc/portage/package.license/kernel Sample license acceptance
sys-kernel/gentoo-sources linux-firmware
sys-kernel/linux-firmware freedist linux-firmware no-source-code
sys-firmware/intel-microcode intel-ucode
Optional: Using systemd as the init system

The remainder of the Gentoo Handbook focuses on OpenRC (the traditional Gentoo init system) as the default init system. If systemd is
desired or if the reader will be installing GNOME 3.8 and later (which requires systemd), please consult the systemd article. It contains
instructions equivalent to the instructions in the following sections of this Handbook. Specifically, it will walk the reader through various init
system commands (systemctl) and systemd-specific services (such as timedatectl, hostnamectl, etc.) needed to establish a
working systemd environment.

Note
Certain applications are heavily dependent on the GNOME software ecosystem and subsequently dependent on systemd. Readers
who are unsure if the GNOME desktop environment will be used can migrate to a systemd profile later.
Timezone
Select the timezone for the system. Look for the available timezones in /usr/share/zoneinfo/, then write it in the /etc/timezone file.
root # ls /usr/share/zoneinfo
Suppose the timezone of choice is Europe/Brussels:
root # echo "Europe/Brussels" > /etc/timezone
Please avoid the /usr/share/zoneinfo/Etc/GMT* timezones as their names do not indicate the expected zones. For instance, GMT-8
is in fact GMT+8.
Next, reconfigure the sys-libs/timezone-data package, which will update the /etc/localtime file for us, based on the
/etc/timezone entry. The /etc/localtime file is used by the system C library to know the timezone the system is in.
root # emerge --config sys-libs/timezone-data

Configure locales
Most users will want to use only one or two locales on their system.
Locales specify not only the language that the user should use to interact with the system, but also what the rules are for sorting strings,
displaying dates and times, etc.
The locales that a system should support should be mentioned in /etc/locale.gen.
root # nano -w /etc/locale.gen
The following locales are an example to get both English (United States) and German (Germany) with the accompanying character
formats (like UTF-8).
FILE /etc/locale.gen Enabling US and DE locales with the appropriate character formats
en_US ISO-8859-1
en_US.UTF-8 UTF-8
de_DE ISO-8859-1
de_DE.UTF-8 UTF-8
 Warning
We strongly suggest to use at least one UTF-8 locale because some applications may require it.
The next step is to run locale-gen. It will generate all the locales specified in the /etc/locale.gen file.
root # locale-gen
To verify that the selected locales are now available, run locale -a.
Once done, it is now time to set the system-wide locale settings. Again we use eselect for this, now with the locale module.
With eselect locale list, the available targets are displayed:
root # eselect locale list

Available targets for the LANG variable:
[1] C
[2] POSIX
[3] en_US
[4] en_US.iso88591
[5] en_US.utf8
[6] de_DE
[7] de_DE.iso88591
[8] de_DE.iso885915
[9] de_DE.utf8
[ ] (free form)
With eselect locale set VALUE the correct locale can be set:
root # eselect locale set 9
Manually, this can still be accomplished through the /etc/env.d/02locale file:
FILE /etc/env.d/02locale Manually setting system locale definitions
LANG="de_DE.UTF-8"
LC_COLLATE="C"
Make sure a locale is set, as the system would otherwise display warnings and errors during kernel builds and other software
deployments later in the installation.
Now reload the environment:
root # env-update && source /etc/profile && export PS1="(chroot) $PS1"
We made a full Localization guide to help the user guide through this process. Another interesting article is the UTF-8 guide for very
specific information to enable UTF-8 on the system.
Installing the sources
The core around which all distributions are built is the Linux kernel. It is the layer between the user programs and the system hardware.
Gentoo provides its users several possible kernel sources. A full listing with description is available at the Kernel overview page.
For amd64-based systems Gentoo recommends the sys-kernel/gentoo-sources package.
Choose an appropriate kernel source and install it using emerge:
root # emerge --ask sys-kernel/gentoo-sources
This will install the Linux kernel sources in /usr/src/ in which a symbolic link called linux will be pointing to the installed kernel source:
root # ls -l /usr/src/linux
lrwxrwxrwx 1 root root 12 Oct 13 11:04 /usr/src/linux -> linux-3.16.5-gentoo
Now it is time to configure and compile the kernel sources. There are two approaches for this:
1. The kernel is manually configured and built.

2. A tool called genkernel is used to automatically build and install the Linux kernel.
We explain the manual configuration as the default choice here as it is the best way to optimize an environment.
Default: Manual configuration

Introduction
Manually configuring a kernel is often seen as the most difficult procedure a Linux user ever has to perform. Nothing is less true - after
configuring a couple of kernels no-one even remembers that it was difficult ;)
However, one thing is true: it is vital to know the system when a kernel is configured manually. Most information can be gathered by
emerging sys-apps/pciutils which contains the lspci command:
root # emerge --ask sys-apps/pciutils

Note
Inside the chroot, it is safe to ignore any pcilib warnings (like pcilib: cannot open /sys/bus/pci/devices) that lspci might throw out.
Another source of system information is to run lsmod to see what kernel modules the installation CD uses as it might provide a nice hint
on what to enable.
Now go to the kernel source directory and execute make menuconfig. This will fire up menu-driven configuration screen.
root # cd /usr/src/linux
root # make menuconfig
The Linux kernel configuration has many, many sections. Let's first list some options that must be activated (otherwise Gentoo will not
function, or not function properly without additional tweaks). We also have a Gentoo kernel configuration guide on the Gentoo wiki that
might help out further.
Activating required options

Make sure that every driver that is vital to the booting of the system (such as SCSI controller, etc.) is compiled in the kernel and not as a
module, otherwise the system will not be able to boot completely.
Next select the exact processor type. It is also recommended to enable MCE features (if available) so that users are able to be notified of
any hardware problems. On some architectures (such as x86_64), these errors are not printed to dmesg, but to /dev/mcelog. This
requires the app-admin/mcelog package.
Also select Maintain a devtmpfs file system to mount at /dev so that critical device files are already available early in the boot process
(CONFIG_DEVTMPFS and CONFIG_DEVTMPFS_MOUNT):
KERNEL Enabling devtmpfs support

Device Drivers --->
Generic Driver Options --->
[*] Maintain a devtmpfs filesystem to mount at /dev
[*] Automount devtmpfs at /dev, after the kernel mounted the rootfs
Verify SCSI disk support has been activated (CONFIG_BLK_DEV_SD):
KERNEL Enabling SCSI disk support
Device Drivers --->

SCSI device support --->
<*> SCSI disk support
Now go to File Systems and select support for the filesystems you use. Don't compile the file system that is used for the root filesystem
as module, otherwise the Gentoo system will not be able to mount the partition. Also select Virtual memory and /proc file system. Select
one or more of the following options as needed by the system (CONFIG_EXT2_FS, CONFIG_EXT3_FS, CONFIG_EXT4_FS,
CONFIG_MSDOS_FS, CONFIG_VFAT_FS, CONFIG_PROC_FS, and CONFIG_TMPFS):
KERNEL Selecting necessary file systems
File systems --->

<*> Second extended fs support
<*> The Extended 3 (ext3) filesystem
<*> The Extended 4 (ext4) filesystem
<*> Reiserfs support
<*> JFS filesystem support
<*> XFS filesystem support
<*> Btrfs filesystem support
DOS/FAT/NT Filesystems --->
<*> MSDOS fs support
<*> VFAT (Windows-95) fs support
Pseudo Filesystems --->

[*] /proc file system support
[*] Tmpfs virtual memory file system support (former shm fs)
If PPPoE is used to connect to the Internet, or a dial-up modem, then enable the following options (CONFIG_PPP,
CONFIG_PPP_ASYNC, and CONFIG_PPP_SYNC_TTY):
KERNEL Selecting PPPoE necessary drivers
Device Drivers --->

Network device support --->
<*> PPP (point-to-point protocol) support
<*> PPP support for async serial ports
<*> PPP support for sync tty ports
The two compression options won't harm but are not definitely needed, neither does the PPP over Ethernet option, that might only be
used by ppp when configured to do kernel mode PPPoE.
Don't forget to include support in the kernel for the network (Ethernet or wireless) cards.
Most systems also have multiple cores at their disposal, so it is important to activate Symmetric multi-processing support
(CONFIG_SMP):
KERNEL Activating SMP support
Processor type and features --->

[*] Symmetric multi-processing support

Note
In multi-core systems, each core counts as one processor.
If USB input devices (like keyboard or mouse) or other USB devices will be used, do not forget to enable those as well
(CONFIG_HID_GENERIC and CONFIG_USB_HID, CONFIG_USB_SUPPORT, CONFIG_USB_XHCI_HCD, CONFIG_USB_EHCI_HCD,
CONFIG_USB_OHCI_HCD):
KERNEL Activating USB support for input devices

Device Drivers --->
HID support --->
-*- HID bus support
<*> Generic HID driver
[*] Battery level reporting for HID devices
USB HID support --->
<*> USB HID transport layer
[*] USB support --->
<*> xHCI HCD (USB 3.0) support
<*> EHCI HCD (USB 2.0) support
<*> OHCI HCD (USB 1.1) support
Architecture specific kernel configuration

Make sure to select IA32 Emulation if 32-bit programs should be supported (CONFIG_IA32_EMULATION). Gentoo installs a multilib
system (mixed 32-bit/64-bit computing) by default, so unless a no-multilib profile is used, this option is required.
KERNEL Selecting processor types and features

[ ] Machine Check / overheating reporting
[ ] Intel MCE Features
[ ] AMD MCE Features
Processor family (AMD-Opteron/Athlon64) --->
( ) Opteron/Athlon64/Hammer/K8
( ) Intel P4 / older Netburst based Xeon
( ) Core 2/newer Xeon
( ) Intel Atom
( ) Generic-x86-64
Executable file formats / Emulations --->
[*] IA32 Emulation
Enable GPT partition label support if that was used previously when partitioning the disk (CONFIG_PARTITION_ADVANCED and
CONFIG_EFI_PARTITION):
KERNEL Enable support for GPT
-*- Enable the block layer --->

Partition Types --->
[*] Advanced partition selection
[*] EFI GUID Partition support
Enable EFI stub support and EFI variables in the Linux kernel if UEFI is used to boot the system (CONFIG_EFI, CONFIG_EFI_STUB,
CONFIG_EFI_MIXED, and CONFIG_EFI_VARS):
KERNEL Enable support for UEFI

[*] EFI runtime service support
[*] EFI stub support
[*] EFI mixed-mode support
Firmware Drivers --->

EFI (Extensible Firmware Interface) Support --->
<*> EFI Variable Support via sysfs
Compiling and installing

With the configuration now done, it is time to compile and install the kernel. Exit the configuration and start the compilation process:
root # make && make modules_install

Note
It is possible to enable parallel builds using make -jX with X being an integer number of parallel tasks that the build process is
allowed to launch. This is similar to the instructions about /etc/portage/make.conf earlier, with the MAKEOPTS variable.
When the kernel has finished compiling, copy the kernel image to /boot/. This is handled by the make install command:
root # make install
This will copy the kernel image into /boot/ together with the System.map file and the kernel configuration file.
Optional: Building an initramfs

In certain cases it is necessary to build an initramfs - an initial ram-based file system. The most common reason is when important file
system locations (like /usr/ or /var/) are on separate partitions. With an initramfs, these partitions can be mounted using the tools
available inside the initramfs.
Without an initramfs, there is a huge risk that the system will not boot up properly as the tools that are responsible for mounting the file
systems need information that resides on those file systems. An initramfs will pull in the necessary files into an archive which is used right
after the kernel boots, but before the control is handed over to the init tool. Scripts on the initramfs will then make sure that the partitions
are properly mounted before the system continues booting.
To install an initramfs, install sys-kernel/genkernel first, then have it generate an initramfs:
root # emerge --ask sys-kernel/genkernel
root # genkernel --install initramfs
In order to enable specific support in the initramfs, such as LVM or RAID, add in the appropriate options to genkernel. See genkernel
--help for more information. In the next example support is enabled for LVM and software RAID (mdadm):
root # genkernel --lvm --mdadm --install initramfs
The initramfs will be stored in /boot/. The resulting file can be found by simply listing the files starting with initramfs:
root # ls /boot/initramfs*
Now continue with Kernel modules.
Alternative: Using genkernel

If a manual configuration looks too daunting, then using genkernel is recommended. It will configure and build the kernel automatically.
genkernel works by configuring a kernel nearly identically to the way the installation CD kernel is configured. This means that when
genkernel is used to build the kernel, the system will generally detect all hardware at boot-time, just like the installation CD does.
Because genkernel doesn't require any manual kernel configuration, it is an ideal solution for those users who may not be comfortable
compiling their own kernels.
Now, let's see how to use genkernel. First, emerge the sys-kernel/genkernel ebuild:
root # emerge --ask sys-kernel/genkernel
Next, edit the /etc/fstab file so that the line containing /boot/ as second field has the first field pointing to the right device. If the
partitioning example from the handbook is followed, then this device is most likely /dev/sda2 with the ext2 file system. This would make
the entry in the file look like so:
root # nano -w /etc/fstab
FILE /etc/fstab Configuring the /boot mountpoint
/dev/sda2 /boot ext2 defaults 0 2

Note
Further in the Gentoo installation, /etc/fstab will be configured again. The /boot setting is needed right now as the genkernel
application reads in this configuration.
Now, compile the kernel sources by running genkernel all. Be aware though, as genkernel compiles a kernel that supports almost all
hardware, this compilation will take quite a while to finish!

Note
If the boot partition doesn't use ext2 or ext3 as filesystem it might be necessary to manually configure the kernel using genkernel
--menuconfig all and add support for this particular filesystem in the kernel (i.e. not as a module). Users of LVM2 will probably
want to add --lvm as an argument as well.
root # genkernel all
Once genkernel completes, a kernel, full set of modules and initial ram disk (initramfs) will be created. We will use the kernel and initrd
when configuring a boot loader later in this document. Write down the names of the kernel and initrd as this information is used when the
boot loader configuration file is edited. The initrd will be started immediately after booting to perform hardware autodetection (just like on
the installation CD) before the "real" system starts up.
root # ls /boot/kernel* /boot/initramfs*
Kernel modules
Configuring the modules

Note
Hardware modules are optional to be listed manually. udev will normally load all hardware modules that are detected to be
connected in most cases. However, it is not harmful for automatically detected modules to be listed. Sometimes exotic hardware
requires help to load their drivers.
List the modules that need to be loaded automatically in /etc/modules-load.d/*.conf files one module per line. Extra options for the
modules, if necessary, should be set in /etc/modprobe.d/*.conf files.
To view all available modules, run the following find command. Don't forget to substitute "<kernel version>" with the version of the
kernel just compiled:
root # find /lib/modules/<kernel version>/ -type f -iname '*.o' -or -iname '*.ko' | less
For instance, to automatically load the 3c59x.ko module (which is the driver for a specific 3Com network card family), edit the
/etc/modules-load.d/network.conf file and enter the module name in it. The actual file name is insignificant to the loader.
root # mkdir -p /etc/modules-load.d

root # nano -w /etc/modules-load.d/network.conf
FILE /etc/modules-load.d/network.conf Force loading 3c59x module
3c59x
Continue the installation with Configuring the system.
Optional: Installing firmware

Some drivers require additional firmware to be installed on the system before they work. This is often the case for network interfaces,
especially wireless network interfaces. Also, modern video chips, from vendors like AMD, NVidia, and Intel when using open source
drivers, often need external firmware files. Most of the firmware is packaged in sys-kernel/linux-firmware :
root # emerge --ask sys-kernel/linux-firmware
Filesystem information
About fstab
Under Linux, all partitions used by the system must be listed in /etc/fstab. This file contains the mount points of those partitions
(where they are seen in the file system structure), how they should be mounted and with what special options (automatically or not,
whether users can mount them or not, etc.)
Creating the fstab file

The /etc/fstab file uses a table-like syntax. Every line consists of six fields, separated by whitespace (space(s), tabs or a mixture).
Each field has its own meaning:
1. The first field shows the block special device or remote filesystem to be mounted. Several kinds of device identifiers are available
for block special device nodes, including paths to device files, filesystem labels and UUIDs, and partition labels and UUIDs.
2. The second field shows the mount point at which the partition should be mounted.
3. The third field shows the filesystem used by the partition.
4. The fourth field shows the mount options used by mount when it wants to mount the partition. As every filesystem has its own
mount options, users are encouraged to read the mount man page (man mount) for a full listing. Multiple mount options are
comma-separated.
5. The fifth field is used by dump to determine if the partition needs to be dumped or not. This can generally be left as 0 (zero).
6. The sixth field is used by fsck to determine the order in which filesystems should be checked if the system wasn't shut down
properly. The root filesystem should have 1 while the rest should have 2 (or 0 if a filesystem check isn't necessary).
 Important
The default /etc/fstab file provided by Gentoo is not a valid fstab file but instead more of a template.
root # nano -w /etc/fstab
In the remainder of the text, we use the default /dev/sd* block device files as partition.
Filesystem labels and UUIDs

Both MBR (BIOS) and GPT include support for filesystem labels and filesystem UUIDs. These attributes can be defined in /etc/fstab
as alternatives for the mount command to use when attempting to find and mount block devices. Filesystem labels and UUIDs are
identified by the LABEL and UUID prefix and can be viewed with the blkid command:
root # blkid
 Warning
If the filesystem inside a partition is wiped, then the filesystem label and the UUID values will be subsequently altered or removed.
Because of uniqueness, readers that are using an MBR-style partition table are recommended to use UUIDs over labels to define
mountable volumes in /etc/fstab.
Partition labels and UUIDs

Users who have gone the GPT route have a couple more 'robust' options available to define partitions in /etc/fstab. Partition labels
and partition UUIDs can be used to identify the block device's individual partition(s), regardless of what filesystem has been chosen for
the partition itself. Partition labels and UUIDs are identified by the PARTLABEL and PARTUUID prefixes respectively and can be viewed
nicely in the terminal by running the blkid command:
root # blkid
While not always true for partition labels, using a UUID to identify a partition in fstab provides a guarantee that the bootloader will not be
confused when looking for a certain volume, even if the filesystem would be changed in the future. Using the older default block device
files (/dev/sd*N) for defining the partitions in fstab is risky for systems that are restarted often and have SATA block devices added
and removed regularly.
The naming for block device files depends on a number of factors, including how and in what order the disks are attached to the system.
They also could show up in a different order depending on which of the devices are detected by the kernel first during the early boot
process. With this being stated, unless one intends to constantly fiddle with the disk ordering, using default block device files is a simple
and straightforward approach.
Let us take a look at how to write down the options for the /boot/ partition. This is just an example, and should be modified according to
the partitioning decisions made earlier in the installation. In our amd64 partitioning example, /boot/ is usually the /dev/sda2 partition,
with ext2 as filesystem. It needs to be checked during boot, so we would write down:
FILE /etc/fstab An example /boot line for /etc/fstab
/dev/sda2 /boot ext2 defaults 0 2
Some users don't want their /boot/ partition to be mounted automatically to improve their system's security. Those people should
substitute defaults with noauto. This does mean that those users will need to manually mount this partition every time they want to use it.
Add the rules that match the previously decided partitioning scheme and append rules for devices such as CD-ROM drive(s), and of
course, if other partitions or drives are used, for those too.
Below is a more elaborate example of an /etc/fstab file:

FILE /etc/fstab A full /etc/fstab example
/dev/sda2 /boot ext2 defaults,noatime 0 2

/dev/sda3 none swap sw 0 0
/dev/sda4 / ext4 noatime 0 1
/dev/cdrom /mnt/cdrom auto noauto,user 0 0
When auto is used in the third field, it makes the mount command guess what the filesystem would be. This is recommended for
removable media as they can be created with one of many filesystems. The user option in the fourth field makes it possible for non-
root users to mount the CD.
To improve performance, most users would want to add the noatime mount option, which results in a faster system since access times
aren't registered (those are not needed generally anyway). This is also recommended for solid state drive (SSD) users, who should also
enable the discard mount option (ext4 and btrfs only for now) which makes the TRIM command work.
Double-check the /etc/fstab file, save and quit to continue.
Networking information
Host and domain information
One of the choices the user has to make is name his/her PC. This seems to be quite easy, but lots of users are having difficulties finding
the appropriate name for their Linux PC. To speed things up, know that the decision is not final - it can be changed afterwards. In the
examples below, the hostname tux is used within the domain homenetwork.
root # nano -w /etc/conf.d/hostname

# Set the hostname variable to the selected host name
hostname="tux"
Second, if a domain name is needed, set it in /etc/conf.d/net. This is only necessary if the ISP or network administrator says so, or if
the network has a DNS server but not a DHCP server. Don't worry about DNS or domain names if the system uses DHCP for dynamic IP
address allocation and network configuration.

Note
The /etc/conf.d/net file does not exist by default, so needs to be created.
root # nano -w /etc/conf.d/net

# Set the dns_domain_lo variable to the selected domain name
dns_domain_lo="homenetwork"

Note
If no domain name is configured, then users will notice they get "This is hostname.(none)" messages at their login screen. This
should then be fixed by editing /etc/issue and deleting the string .\O from that file.
If a NIS domain is needed (users that do not know this will not need one), define that one too:

# Set the nis_domain_lo variable to the selected NIS domain name
nis_domain_lo="my-nisdomain"

Note
For more information on configuring DNS and NIS, please read the examples provided in /usr/share/doc/netifrc-
*/net.example.bz2 which can be read using bzless. Also, it might be interesting to install net-dns/openresolv to help manage
the DNS/NIS setup.
Configuring the network

During the Gentoo Linux installation, networking was already configured. However, that was for the installation CD itself and not for the
installed environment. Right now, the network configuration is made for the installed Gentoo Linux system.

Note
More detailed information about networking, including advanced topics like bonding, bridging, 802.1Q VLANs or wireless networking
is covered in the Gentoo Network Configuration section.
All networking information is gathered in /etc/conf.d/net. It uses a straightforward yet perhaps not intuitive syntax. But don't fear,
everything is explained below. A fully commented example that covers many different configurations is available in
/usr/share/doc/netifrc-*/net.example.bz2.
First install net-misc/netifrc :
root # emerge --ask --noreplace net-misc/netifrc
DHCP is used by default. For DHCP to work, a DHCP client needs to be installed. This is described later in Installing Necessary System
Tools.
If the network connection needs to be configured because of specific DHCP options or because DHCP is not used at all, then open
/etc/conf.d/net:
Set both config_eth0 and routes_eth0 to enter IP address information and routing information:

Note
This assumes that the network interface will be called eth0. This is, however, very system dependent. It is recommended to assume
that the interface is named the same as the interface name when booted from the installation media if the installation media is
sufficiently recent. More information can be found in Network Interface Naming.
FILE /etc/conf.d/net Static IP definition
config_eth0="192.168.0.2 netmask 255.255.255.0 brd 192.168.0.255"

routes_eth0="default via 192.168.0.1"
To use DHCP, define config_eth0:
FILE /etc/conf.d/net DHCP definition
config_eth0="dhcp"
Please read /usr/share/doc/netifrc-*/net.example.bz2 for a list of all available options. Be sure to also read up on the DHCP
client man page if specific DHCP options need to be set.
If the system has several network interfaces, then repeat the above steps for config_eth1, config_eth2, etc.
Now save the configuration and exit to continue.
Automatically start networking at boot

To have the network interfaces activated at boot, they need to be added to the default runlevel.
root # cd /etc/init.d
root # ln -s net.lo net.eth0
root # rc-update add net.eth0 default
If the system has several network interfaces, then the appropriate net.* files need to be created just like we did with net.eth0.
If after booting the system we find out that the assumption about the network interface name (which is currently documented as eth0 )
was wrong, then execute the following steps to rectify this:
1. Update the /etc/conf.d/net file with the correct interface name (like enp3s0 instead of eth0 ).
2. Create new symbolic link (like /etc/init.d/net.enp3s0).
3. Remove the old symbolic link (rm /etc/init.d/net.eth0).
4. Add the new one to the default runlevel.
5. Remove the old one using rc-update del net.eth0 default.
The hosts file

Next inform Linux about the network environment. This is defined in /etc/hosts and helps in resolving host names to IP addresses for
hosts that aren't resolved by the nameserver.
root # nano -w /etc/hosts
FILE /etc/hosts Filling in the networking information

# This defines the current system and must be set
127.0.0.1 tux.homenetwork tux localhost
# Optional definition of extra systems on the network

192.168.0.5 jenny.homenetwork jenny
192.168.0.6 benny.homenetwork benny
Save and exit the editor to continue.
Optional: Get PCMCIA working

PCMCIA users should now install the sys-apps/pcmciautils package.
root # emerge --ask sys-apps/pcmciautils
System information
Root password
Set the root password using the passwd command.
root # passwd
The root Linux account is an all-powerful account, so pick a strong password. Later an additional regular user account will be created for
daily operations.
Init and boot configuration

Gentoo (at least when using OpenRC) uses /etc/rc.conf to configure the services, startup, and shutdown of a system. Open up
/etc/rc.conf and enjoy all the comments in the file. Review the settings and change where needed.
root # nano -w /etc/rc.conf
Next, open /etc/conf.d/keymaps to handle keyboard configuration. Edit it to configure and select the right keyboard.
root # nano -w /etc/conf.d/keymaps
Take special care with the keymap variable. If the wrong keymap is selected, then weird results will come up when typing on the
keyboard.
Finally, edit /etc/conf.d/hwclock to set the clock options. Edit it according to personal preference.
root # nano -w /etc/conf.d/hwclock
If the hardware clock is not using UTC, then it is necessary to set clock="local" in the file. Otherwise the system might show clock
skew behavior.
System logger
Some tools are missing from the stage3 archive because several packages provide the same functionality. It is now up to the user to
choose which ones to install.
The first tool to decide on has to provide logging facilities for the system. Unix and Linux have an excellent history of logging capabilities -
if needed, everything that happens on the system can be logged in log files. This happens through the system logger.
Gentoo offers several system logger utilities. A few of these include:
app-admin/sysklogd - Offers the traditional set of system logging daemons. The default logging configuration works well out of the
box which makes this package a good option for beginners.
app-admin/syslog-ng - An advanced system logger. Requires additional configuration for anything beyond logging to one big file.
More advanced users may choose this package based on its logging potential; be aware additional configuration is a necessity for
any kind of smart logging.
app-admin/metalog - A highly-configurable system logger.
Others are available through Portage as well - the number of available packages increases on a daily basis.
 Tip
If sysklogd or syslog-ng are going to be used, it is recommended to install and configure logrotate afterwards as those system
loggers don't provide any rotation mechanism for the log files.
 Tip
systemd provides its own logging facility called the "journal". Installing a separate syslog provider is optional on systems running
systemd, and may require additional configuration to have the syslog daemon read messages from the journal.
To install the system logger of choice, emerge it and have it added to the default runlevel using rc-update. The following example
installs app-admin/sysklogd :
root # emerge --ask app-admin/sysklogd
root # rc-update add sysklogd default
Optional: Cron daemon

Next is the cron daemon. Although it is optional and not required for every system, it is wise to install one.
A cron daemon executes scheduled commands. It is very handy if some command needs to be executed regularly (for instance daily,
weekly or monthly).
Gentoo offers several possible cron daemons, including sys-process/bcron , sys-process/dcron , sys-process/fcron , and sys-
process/cronie . Installing one of them is similar to installing a system logger. The following example uses sys-process/cronie :
root # emerge --ask sys-process/cronie
root # rc-update add cronie default
If dcron or fcron are used, an additional initialization command needs to be executed:
root # crontab /etc/crontab
Optional: File indexing

In order to index the file system to provide faster file location capabilities, install sys-apps/mlocate .
root # emerge --ask sys-apps/mlocate
Optional: Remote access

To be able to access the system remotely after installation, add the sshd init script to the default runlevel:
root # rc-update add sshd default
If serial console access is needed (which is possible in case of remote servers), uncomment the serial console section in /etc/inittab:
root # nano -w /etc/inittab

# SERIAL CONSOLES
s0:12345:respawn:/sbin/agetty 9600 ttyS0 vt100
s1:12345:respawn:/sbin/agetty 9600 ttyS1 vt100
Filesystem tools
Depending on the filesystems used, it is necessary to install the required file system utilities (for checking the filesystem integrity, creating
additional file systems etc.). Note that tools for managing ext2, ext3, or ext4 filesystems (sys-fs/e2fsprogs ) are already installed as a
part of the @system set.
The following table lists the tools to install if a certain filesystem is used:
Filesystem Package
Ext2, 3, and 4 sys-fs/e2fsprogs
XFS sys-fs/xfsprogs
ReiserFS sys-fs/reiserfsprogs
JFS sys-fs/jfsutils
VFAT (FAT32, ...) sys-fs/dosfstools
Btrfs sys-fs/btrfs-progs
 Tip
For more information on filesystems in Gentoo see the filesystem article.
Networking tools
If there is no need for any additional networking tools, continue immediately with the section on Configuring a bootloader.
Installing a DHCP client

 Important
Although optional, the majority of users will find that they need a DHCP client to connect to the DHCP server on their network.
Please take this opportunity to install a DHCP client. If this step is forgotten, then the system might not be able to get on the network
thus making it impossible to download a DHCP client afterward.
In order for the system to automatically obtain an IP address for one or more network interface(s) using netifrc scripts, it is necessary to
install a DHCP client. We recommend the use of net-misc/dhcpcd although many other DHCP clients are available through the Gentoo
repository:
root # emerge --ask net-misc/dhcpcd
More information on dhcpcd can be found in the dhcpcd article.
Optional: Installing a PPPoE client

If PPP is used to connect to the internet, install the net-dialup/ppp package:
root # emerge --ask net-dialup/ppp
Optional: Install wireless networking tools

If the system will be connecting to wireless networks, install the net-wireless/iw package for Open or WEP networks and/or the net-
wireless/wpa_supplicant package for WPA or WPA2 networks. iw is also a useful basic diagnostic tool for scanning wireless networks.
root # emerge --ask net-wireless/iw net-wireless/wpa_supplicant
Now continue with Configuring the bootloader.
Selecting a boot loader

With the Linux kernel configured, system tools installed and configuration files edited, it is time to install the last important piece of a
Linux installation: the boot loader.
The boot loader is responsible for firing up the Linux kernel upon boot - without it, the system would not know how to proceed when the
power button has been pressed.
For amd64, we document how to configure either GRUB2 or LILO for BIOS based systems, and GRUB2 or efibootmgr for UEFI systems.
In this section of the Handbook a delineation has been made between emerging the boot loader's package and installing a boot loader to
a system disk. Here the term emerge will be used to ask Portage to make the software package available to the system. The term install
will signify the boot loader copying files or physically modifying appropriate sections of the system's disk drive in order to render the boot
loader activated and ready to operate on the next power cycle.
Default: GRUB2
Previously, Gentoo Linux used what is now called GRUB Legacy as the recommended boot loader. As the name implies, the older GRUB
package is no longer actively maintained and has been superseded by GRUB2. For more information about the legacy GRUB, please
refer to its GRUB article.
By default, the majority of Gentoo systems now rely upon GRUB2 (found in the sys-boot/grub package), which is the direct successor
to GRUB Legacy. With no additional configuration, GRUB2 gladly supports older BIOS ("pc") systems. With a small amount of
configuration, necessary before build time, GRUB2 can support more than a half a dozen additional platforms. For more information,
consult the Prerequisites section of the GRUB2 article.
Emerge
When using an older BIOS system supporting only MBR partition tables, no additional configuration is needed in order to emerge GRUB:
root # emerge --ask --verbose sys-boot/grub:2
A note for UEFI users: running the above command will output the enabled GRUB_PLATFORMS values before emerging. When using
UEFI capable systems, users will need to ensure GRUB_PLATFORMS="efi-64" is enabled (as it is the case by default). If that is not the
case for the setup, GRUB_PLATFORMS="efi-64" will need to be added to the /etc/portage/make.conf file before emerging GRUB2
so that the package will be built with EFI functionality:
root # echo 'GRUB_PLATFORMS="efi-64"' >> /etc/portage/make.conf
root # emerge --ask sys-boot/grub:2
If GRUB2 was somehow emerged without enabling GRUB_PLATFORMS="efi-64" , the line (as shown above) can be added to
make.conf then and dependencies for the world package set re-calculated by passing the --update --newuse options to emerge:
root # emerge --ask --update --newuse --verbose sys-boot/grub:2
The GRUB2 software has now been merged to the system, but not yet installed.
Install
Next, install the necessary GRUB2 files to the /boot/grub/ directory via the grub-install command. Presuming the first disk (the one
where the system boots from) is /dev/sda, one of the following commands will do:
When using BIOS:

root # grub-install /dev/sda
When using UEFI:
 Important
Make sure the EFI system partition has been mounted before running grub-install. It is possible for grub-install to install
the GRUB EFI file (grubx64.efi) into the wrong directory without providing any indication the wrong directory was used.
root # grub-install --target=x86_64-efi --efi-directory=/boot

Note
Modify the --efi-directory option to the root of the EFI System Partition. This is necessary if the /boot partition was not
formatted as a FAT variant.
 Important
If grub_install returns an error like Could not prepare Boot variable: Read-only file system , it may be
necessary to remount the efivars special mount as read-write in order to succeed:
root # mount -o remount,rw /sys/firmware/efi/efivars
Some motherboard manufacturers seem to only support the /efi/boot/ directory location for the .EFI file in the EFI System Partition
(ESP). The GRUB installer can perform this operation automatically with the --removable option. Verify the ESP is mounted before
running the following commands. Presuming the ESP is mounted at /boot (as suggested earlier), execute:
root # grub-install --target=x86_64-efi --efi-directory=/boot --removable
This creates the default directory defined by the UEFI specification, and then copies the grubx64.efi file to the 'default' EFI file location
defined by the same specification.
Configure
Next, generate the GRUB2 configuration based on the user configuration specified in the /etc/default/grub file and /etc/grub.d
scripts. In most cases, no configuration is needed by users as GRUB2 will automatically detect which kernel to boot (the highest one
available in /boot/) and what the root file system is. It is also possible to append kernel parameters in /etc/default/grub using the
GRUB_CMDLINE_LINUX variable.
To generate the final GRUB2 configuration, run the grub-mkconfig command:
root # grub-mkconfig -o /boot/grub/grub.cfg

Generating grub.cfg ...
Found linux image: /boot/vmlinuz-3.16.5-gentoo
Found initrd image: /boot/initramfs-genkernel-amd64-3.16.5-gentoo
done
The output of the command must mention that at least one Linux image is found, as those are needed to boot the system. If an initramfs
is used or genkernel was used to build the kernel, the correct initrd image should be detected as well. If this is not the case, go to
/boot/ and check the contents using the ls command. If the files are indeed missing, go back to the kernel configuration and
installation instructions.
 Tip
The os-prober utility can be used in conjunction with GRUB2 to detect other operating systems from attached drives. Windows 7,
8.1, 10, and other distributions of Linux are detectable. Those desiring dual boot systems should emerge the sys-boot/os-prober
package then re-run the grub-mkconfig command (as seen above). If detection problems are encountered be sure to read the
GRUB2 article in its entirety before asking the Gentoo community for support.
Alternative 1: LILO
Emerge
LILO, the LInuxLOader, is the tried and true workhorse of Linux boot loaders. However, it lacks features when compared to GRUB. LILO
is still used because, on some systems, GRUB does not work and LILO does. Of course, it is also used because some people know LILO
and want to stick with it. Either way, Gentoo supports both bootloaders.
Installing LILO is a breeze; just use emerge.
root # emerge --ask sys-boot/lilo
Configure
To configure LILO, first create /etc/lilo.conf:
root # nano -w /etc/lilo.conf
In the configuration file, sections are used to refer to the bootable kernel. Make sure that the kernel files (with kernel version) and
initramfs files are known, as they need to be referred to in this configuration file.

Note
If the root filesystem is JFS, add an append="ro" line after each boot item since JFS needs to replay its log before it allows read-
write mounting.
FILE /etc/lilo.conf Example LILO configuration
boot=/dev/sda # Install LILO in the MBR

prompt # Give the user the chance to select another section
timeout=50 # Wait 5 (five) seconds before booting the default section
default=gentoo # When the timeout has passed, boot the "gentoo" section
compact # This drastically reduces load time and keeps the map file smaller; may fail o
n some systems
image=/boot/vmlinuz-3.16.5-gentoo
label=gentoo # Name we give to this section
read-only # Start with a read-only root. Do not alter!
root=/dev/sda4 # Location of the root filesystem
label=gentoo.rescue # Name we give to this section
read-only # Start with a read-only root. Do not alter!
root=/dev/sda4 # Location of the root filesystem
append="init=/bin/bb" # Launch the Gentoo static rescue shell
# The next two lines are for dual booting with a Windows system.
# In this example, Windows is hosted on /dev/sda6.
other=/dev/sda6
label=windows

Note
If a different partitioning scheme and/or kernel image is used, adjust accordingly.
If an initramfs is necessary, then change the configuration by referring to this initramfs file and telling the initramfs where the root device
is located:
FILE /etc/lilo.conf Adding initramfs information to a boot entry
label=gentoo
read-only
append="root=/dev/sda4"
initrd=/boot/initramfs-genkernel-amd64-3.16.5-gentoo
If additional options need to be passed to the kernel, use an append statement. For instance, to add the video statement to enable
framebuffer:
FILE /etc/lilo.conf Adding video parameter to the boot options
label=gentoo
read-only
root=/dev/sda4
append="video=uvesafb:mtrr,ywrap,1024x768-32@85"
Users that used genkernel should know that their kernels use the same boot options as is used for the installation CD. For instance, if
SCSI device support needs to be enabled, add doscsi as kernel option.
Now save the file and exit.
Install
To finish up, run the /sbin/lilo executable so LILO can apply the /etc/lilo.conf settings to the system (i.e. install itself on the
disk). Keep in mind that /sbin/lilo must be executed each time a new kernel is installed or a change has been made to the
lilo.conf file in order for the system to boot if the filename of the kernel has changed.
root # /sbin/lilo
Alternative 2: efibootmgr
On UEFI based systems, the UEFI firmware on the system (in other words the primary bootloader), can be directly manipulated to look
for UEFI boot entries. Such systems do not need to have additional (also known as secondary) bootloaders like GRUB2 in order to help
boot the system. With that being said, the reason EFI-based bootloaders such as GRUB2 exist is to extend the functionality of UEFI
systems during the boot process. Using efibootmgr is really for those who desire to take a minimalist (although more rigid) approach to
booting their system; using GRUB2 (see above) is easier for the majority of users because it offers a flexible approach when booting
UEFI systems.
Remember sys-boot/efibootmgr application is not a bootloader; it is a tool to interact with the UEFI firmware and update its settings, so
that the Linux kernel that was previously installed can be booted with additional options (if necessary), or to allow multiple boot entries.
This interaction is done through the EFI variables (hence the need for kernel support of EFI vars).
Be sure to read through the EFI stub kernel article before continuing. The kernel must have specific options enabled to be directly
bootable by the system's UEFI firmware. It might be necessary to recompile the kernel. It is also a good idea to take a look at the
efibootmgr article.

Note
To reiterate, efibootmgr is not a requirement to boot an UEFI system. The Linux kernel itself can be booted immediately, and
additional kernel command-line options can be built-in to the Linux kernel (there is a kernel configuration option called that allows
the user to specify boot parameters as command-line options. Even an initramfs can be 'built-in' to the kernel.
Those that have decided to take this approach must install the software:
root # emerge --ask sys-boot/efibootmgr
Then, create the /boot/efi/boot/ location, and then copy the kernel into this location, calling it bootx64.efi:
root # mkdir -p /boot/efi/boot

root # cp /boot/vmlinuz-* /boot/efi/boot/bootx64.efi
Next, tell the UEFI firmware that a boot entry called "Gentoo" is to be created, which has the freshly compiled EFI stub kernel:
root # efibootmgr --create --disk /dev/sda --part 2 --label "Gentoo" --loader "\efi\boot\bootx64.efi"
If an initial RAM file system (initramfs) is used, add the proper boot option to it:
root # efibootmgr -c -d /dev/sda -p 2 -L "Gentoo" -l "\efi\boot\bootx64.efi" initrd='\initramfs-genkernel-

amd64-3.16.5-gentoo'

Note
The use of \ as directory separator is mandatory when using UEFI definitions.
With these changes done, when the system reboots, a boot entry called "Gentoo" will be available.
Alternative 3: Syslinux
Syslinux is yet another bootloader alternative for the amd64 architecture. It supports MBR and, as of version 6.00, it supports EFI boot.
PXE (network) boot and lesser-known options are also supported. Although Syslinux is a popular bootloader for many it is unsupported
by the Handbook. Readers can find information on emerging and then installing this bootloader in the Syslinux article.
Rebooting the system

Exit the chrooted environment and unmount all mounted partitions. Then type in that one magical command that initiates the final, true
test: reboot.
root # exit
cdimage ~# cd
cdimage ~# umount -l /mnt/gentoo/dev{/shm,/pts,}
cdimage ~# umount -R /mnt/gentoo
cdimage ~# reboot
Do not forget to remove the bootable CD, otherwise the CD might be booted again instead of the new Gentoo system.
Once rebooted in the freshly installed Gentoo environment, finish up with Finalizing the Gentoo installation.
User administration
Adding a user for daily use
Working as root on a Unix/Linux system is dangerous and should be avoided as much as possible. Therefore it is strongly recommended
to add a user for day-to-day use.
The groups the user is member of define what activities the user can perform. The following table lists a number of important groups:
Group Description
audio Be able to access the audio devices.
cdrom Be able to directly access optical devices.
floppy Be able to directly access floppy devices.
games Be able to play games.
portage Be able to access portage restricted resources.
usb Be able to access USB devices.
video Be able to access video capturing hardware and doing hardware

acceleration.
wheel Be able to use su.
For instance, to create a user called larry who is member of the wheel, users, and audio groups, log in as root first (only root can create
users) and run useradd:
Login: root
Password: (Enter the root password)
root # useradd -m -G users,wheel,audio -s /bin/bash larry

root # passwd larry
Password: (Enter the password for larry)
Re-enter password: (Re-enter the password to verify)
If a user ever needs to perform some task as root, they can use su - to temporarily receive root privileges. Another way is to use the
sudo package which is, if correctly configured, very secure.
Disk cleanup
Removing tarballs
With the Gentoo installation finished and the system rebooted, if everything has gone well, we can now remove the downloaded stage3
tarball from the hard disk. Remember that they were downloaded to the / directory.
root # rm /stage3-*.tar.*
Where to go from here

Documentation
Not sure where to go from here? There are many paths to explore... Gentoo provides its users with lots of possibilities and therefore has
lots of documented (and less documented) features to explore here on the wiki and on other Gentoo related sub-domains (see the
Gentoo online section below).
Readers should definitely take a look at the next part of the Gentoo Handbook entitled Working with Gentoo which explains how to keep
the software up to date, install additional software packages, details on USE flags, the OpenRC init system, and various other informative
topics relating to managing a Gentoo system post-installation.
Apart from the handbook, readers should also feel encouraged to explore other corners of the Gentoo wiki to find additional, community-
provided documentation. The Gentoo wiki team also offers a documentation topic overview which lists a selection of wiki articles by
category. For instance, it refers to the localization guide to make a system feel more at home (particularly useful for users who speak
English as a second language).
Gentoo online
 Important
Readers should note that all official Gentoo sites online are governed by Gentoo's code of conduct. Being active in the Gentoo
community is a privilege, not a right, and users should be aware that the code of conduct exists for a reason.
With the exception of the Freenode hosted internet relay chat (IRC) network and the mailing lists, most Gentoo websites require an
account on a per site basis in order to ask questions, open a discussion, or enter a bug.
Forums and IRC

Every user is welcome on our Gentoo forums or on one of our internet relay chat channels . It is easy to search for the forums to see
if an issue experienced on a fresh Gentoo install has been discovered in the past and resolved after some feedback. The likelihood of
other users experiencing the installation issues by first-time Gentoo can be surprising. It is advised users search the forums and the wiki
before asking for assistance in Gentoo support channels.
Mailing lists
Several mailing lists are available to the community members who prefer to ask for support or feedback over email rather than create
a user account on the forums or IRC. Users will need to follow the instructions in order to subscribe to specific mailing lists.
Bugs
Sometimes after reviewing the wiki, searching the forums, and seeking support in the IRC channel or mailing lists there is no known
solution to a problem. Generally this is a sign to open a bug on Gentoo's Bugzilla site .
Development guide
Readers who desire to learn more about developing Gentoo can take a look at the Development guide . This guide provides
instructions on writing ebuilds, working with eclasses, and provides definitions for many general concepts behind Gentoo development.
Closing thoughts
Gentoo is a robust, flexible, and excellently maintained distribution. The developer community is happy to hear feedback on how to make
Gentoo an even better distribution.
As a reminder, any feedback for this handbook should follow the guidelines detailed in the How do I improve the Handbook? section at
the beginning of the handbook.
We look forward to seeing how our users will choose to implement Gentoo!
This page was last edited on 4 January 2015, at 15:16.

Privacy policy
About Gentoo Wiki
Disclaimers
 © 2001–2019 Gentoo Foundation, Inc.

Gentoo is a trademark of the Gentoo Foundation, Inc. The contents of this document, unless otherwise expressly stated, are
 licensed under the CC-BY-SA-3.0 license. The Gentoo Name and Logo Usage Guidelines apply.

Install Gentoo

Uploaded by

Copyright:

Available Formats

Install Gentoo

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Install Gentoo

Uploaded by

Copyright:

Available Formats



Gentoo Linux amd64 Handbook: Installing Gentoo

How the installation is structured

1 The user is in a working environment ready to install Gentoo.

2 The Internet connection is ready to install Gentoo.

3 The hard disks are initialized to host the Gentoo installation.

6 The Linux kernel is installed.

8 The necessary system tools are installed.

9 The proper boot loader has been installed and configured.

10 The freshly installed Gentoo Linux environment is ready to be explored.

Installation options for Gentoo

AMD64 livedisk hardware requirements

Memory 256 MB 512 MB

Disk space 2.5 GB (excluding swap space)

Swap space At least 256 MB

Gentoo Linux installation media

The Minimal Installation CD is called install-amd64-minimal-<release>.iso.

The occasional Gentoo LiveDVD

What are stages then?

1. Go to the releases/ directory.

CODE Example list of downloadable files at releases/amd64/autobuilds/current-iso/

[DIR] hardened/ 05-Dec-2014 01:42 -

Verifying the downloaded files

Microsoft Windows based verification

user $ gpg --keyserver hkps://hkps.pool.sks-keyservers.net --recv-keys 0xBB572E0E2D182910

user $ wget -O- https://gentoo.org/.well-known/openpgpkey/hu/wtktzo4gyuhzu8a4z5fdj3fgmr1u6tob?l=releng |

0K .......... .......... .......... .... 100% 11.9M=0.003s

2019-04-19 20:46:32 (11.9 MB/s) - written to stdout [35444/35444]

gpg: key 9E6438C817072058: 84 signatures not checked due to missing keys

Next verify the cryptographic signature of the .DIGESTS.asc file:

user $ gpg --verify install-amd64-minimal-20141204.iso.DIGESTS.asc

user $ grep -A 1 -i sha512 install-amd64-minimal-20141204.iso.DIGESTS.asc

user $ sha512sum install-amd64-minimal-20141204.iso

Burning with Microsoft Windows

Burning with Linux

user $ cdrecord dev=/dev/sr0 install-amd64-minimal-20141204.iso

Logical volume/device management

boot: gentoo dopcmcia

Extra hardware configuration

root # modprobe 8139too

Optional: User accounts

To change the root password, use the passwd utility:

In the next example, a user called john is created:

root # useradd -m -G users john

Optional: Viewing documentation while installing

user $ links https://wiki.gentoo.org/wiki/Handbook:AMD64

To go back to the original terminal, press Alt + F1 .

Optional: Starting the SSH daemon

root # rc-service sshd start

Determine interface names

Optional: Configure any proxies

To set up an HTTP proxy (for HTTP and HTTPS traffic):

root # export http_proxy="http://proxy.gentoo.org:8080"

To set up an FTP proxy:

root # export ftp_proxy="ftp://proxy.gentoo.org:8080"

To set up an RSYNC proxy:

CODE Adding username/password to the proxy variable

Testing the network

root # ping -c 3 www.gentoo.org