Handbook:X86/Full/Installation

Welcome[edit | edit source]

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 file a bug report.

How the installation is structured[edit | edit source]

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:

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, the choice that Gentoo believes most users will make.

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[edit | edit source]

Gentoo can be installed in many different ways. It can be downloaded and installed from official Gentoo installation media such as our bootable ISO images. 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.

We also provide a Gentoo installation tips and tricks document that might be useful.

Troubles[edit | edit source]

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.

Although this document is architecture-specific, it may contain references to other architectures as well, because large parts of the Gentoo Handbook use text that is identical for all architectures (to avoid duplication of effort). Such references have been kept 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.

Minimal installation CD[edit | edit source]

The Gentoo minimal installation CD is a bootable image: a self-contained 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-x86-minimal-<release>.iso.

The occasional Gentoo LiveDVD[edit | edit source]

Occasionally, a special DVD image is crafted which can be used to install Gentoo. The instructions in this chapter target the Minimal Installation CD, so things might be a bit different when booting from the LiveDVD. 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?[edit | edit source]

A stage3 tarball is an archive containing a profile specific minimal Gentoo environment. Stage3 tarballs are suitable to continue the Gentoo installation using the instructions in this handbook. Previously, the handbook described the installation using one of three stage tarballs. Gentoo does not offer stage1 and stage2 tarballs for download any more since these are mostly for internal use and for bootstrapping Gentoo on new architectures.

Stage3 tarballs can be downloaded from releases/x86/autobuilds/ on any of the official Gentoo mirrors. Stage files update frequently and are not included in official installation images.

Obtain the media[edit | edit source]

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

Inside this location, the installation media file is the file with the .iso suffix. For instance, take a look at the following listing:

[DIR] hardened/                                          05-Dec-2014 01:42    -   
[   ] install-x86-minimal-20141204.iso                 04-Dec-2014 21:04  208M  
[   ] install-x86-minimal-20141204.iso.CONTENTS        04-Dec-2014 21:04  3.0K  
[   ] install-x86-minimal-20141204.iso.DIGESTS         04-Dec-2014 21:04  740   
[TXT] install-x86-minimal-20141204.iso.DIGESTS.asc     05-Dec-2014 01:42  1.6K  
[   ] stage3-x86-20141204.tar.bz2                      04-Dec-2014 21:04  198M  
[   ] stage3-x86-20141204.tar.bz2.CONTENTS             04-Dec-2014 21:04  4.6M  
[   ] stage3-x86-20141204.tar.bz2.DIGESTS              04-Dec-2014 21:04  720   
[TXT] stage3-x86-20141204.tar.bz2.DIGESTS.asc          05-Dec-2014 01:42  1.5K

In the above example, the install-x86-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[edit | edit source]

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

gpg: requesting key 0xBB572E0E2D182910 from hkp server pool.sks-keyservers.net
gpg: key 0xBB572E0E2D182910: "Gentoo Linux Release Engineering (Automated Weekly Release Key) <releng@gentoo.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

--2019-04-19 20:46:32--  https://gentoo.org/.well-known/openpgpkey/hu/wtktzo4gyuhzu8a4z5fdj3fgmr1u6tob?l=releng
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) <releng@gentoo.org>" 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) <releng@gentoo.org>" imported
gpg: Total number processed: 2
gpg:               imported: 2
gpg: no ultimately trusted keys found

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) <releng@gentoo.org>" [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

# SHA512 HASH
364d32c4f8420605f8a9fa3a0fc55864d5b0d1af11aa62b7a4d4699a427e5144b2d918225dfb7c5dec8d3f0fe2cddb7cc306da6f0cef4f01abec33eec74f3024  install-x86-minimal-20141204.iso
--
# SHA512 HASH
0719a8954dc7432750de2e3076c8b843a2c79f5e60defe43fcca8c32ab26681dfb9898b102e211174a895ff4c8c41ddd9e9a00ad6434d36c68d74bd02f19b57f  install-x86-minimal-20141204.iso.CONTENTS

364d32c4f8420605f8a9fa3a0fc55864d5b0d1af11aa62b7a4d4699a427e5144b2d918225dfb7c5dec8d3f0fe2cddb7cc306da6f0cef4f01abec33eec74f3024  install-x86-minimal-20141204.iso

Burning a disk[edit | edit source]

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.

Booting the installation media[edit | edit source]

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.

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:

Extra hardware configuration[edit | edit source]

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:

Optional: User accounts[edit | edit source]

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:

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:

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:

Optional: Viewing documentation while installing[edit | edit source]

Optional: Starting the SSH daemon[edit | edit source]

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:

To be able to use sshd, the network needs to function properly. Continue with the chapter on Configuring the network.

Determine interface names[edit | edit source]

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 

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

Optional: Configure any proxies[edit | edit source]

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

To set up an FTP proxy:

To set up an RSYNC proxy:

If the proxy requires a username and password, use the following syntax for the variable:

http://username:password@proxy.gentoo.org:8080

Testing the network[edit | edit source]

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.

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

Default: Using net-setup[edit | edit source]

The simplest way to set up networking if it didn't get configured automatically is to run the net-setup script:

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[edit | edit source]

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.

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[edit | edit source]

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:

Then adjust /etc/ppp/options.pptp if necessary:

When all that is done, run pptp (along with the options that couldn't be set in options.pptp) to connect the server:

Now continue with Preparing the disks.

Loading the appropriate network modules[edit | edit source]

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:

If a driver is found for the network device, use modprobe to load the kernel module. For instance, to load the pcnet32 module:

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

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:

eth0: error fetching interface information: Device not found

The available network interface names on the system can be listed through the /sys file system:

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[edit | edit source]

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:

Some network administrators require that the hostname and domainname provided by the DHCP server is used by the system. In that case, use:

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[edit | edit source]

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:

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:

Not connected.

or

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

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

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[edit | edit source]

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:

IP Address (numbers):   192.168.0.2
IP Address (bits):      11000000 10101000 00000000 00000010
                        -------- -------- -------- --------
                           192      168       0        2

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.

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.

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:

Using ifconfig and route[edit | edit source]

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:

Set up routing using route. Substitute ${GATEWAY} with the right gateway IP address:

Now open /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:

nameserver ${NAMESERVER1}
nameserver ${NAMESERVER2}

Now test the network by pinging an Internet server (like Google's 8.8.8.8 or Cloudflare's 1.1.1.1). Once connected, continue with Preparing the disks.

Block devices[edit | edit source]

Let's take a good look at disk-oriented aspects of Gentoo Linux and Linux in general, including block devices, partitions, and Linux filesystems. Once the ins and outs of disks are understood, partitions and filesystems can be established for installation.

To begin, let's look at block devices. SCSI and Serial ATA drives are both labeled under device handles such as: /dev/sda, /dev/sdb, /dev/sdc, etc. On more modern machines, PCI Express based NVMe solid state disks have device handles such as /dev/nvme0n1, /dev/nvme0n2, etc.

The following table will help readers determine where to find a certain type of block device on the system:

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 SATA, SCSI, or something else. The program can simply address the storage on the disk as a bunch of contiguous, randomly-accessible 4096-byte (4K) blocks.

Partition tables[edit | edit source]

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 x86 systems, these are called partitions. There are currently two standard partitioning technologies in use: MBR (sometimes also called DOS disklabel) and GPT; these are tied to the two boot process types: legacy BIOS boot and UEFI.

Advanced storage[edit | edit source]

The x86 Installation CDs provide support for Logical Volume Manager (LVM). LVM increases the flexibility offered by the partitioning setup. It allows to combine partitions and disks into volume groups and define RAID groups or caches on fast SSDs for slow HDs. 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[edit | edit source]

Throughout the remainder of the handbook, we will discuss and explain two cases: 1) GPT partition table and UEFI boot, and 2) MBR partition table and legacy BIOS boot. While it is possible to mix and match, that goes beyond the scope of this manual. As already stated above, installations on modern hardware should use GPT partition table and UEFI boot; as an exception from this rule, MBR and BIOS boot is still frequently used in virtualized (cloud) environments.

The following partitioning scheme will be used as a simple example layout:

If this suffices as information, the advanced reader can directly skip ahead to the actual partitioning.

Both fdisk and parted are partitioning utilities. fdisk is well known, stable, and recommended for the MBR partition layout. parted was one of the first Linux block device management utilities to support GPT partitions, and provides an alternative. Here, fdisk is used since it has a better text-based user interface.

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.

How many partitions and how big?[edit | edit source]

The design of disk partition layout is highly dependent on the demands of the system and the file system(s) applied to the device. If there are lots of users, then it is advised to have /home on a separate partition which will increase security and make backups and other types of maintenance easier. If Gentoo is being installed to perform as a mail server, then /var should be a separate partition as all mails are stored inside the /var directory. Game servers may have a separate /opt partition since most gaming server software is installed therein. The reason for these recommendations is similar to the /home directory: security, backups, and maintenance.

In most situations on Gentoo, /usr and /var should be kept relatively large in size. /usr hosts the majority of applications available on the system and the Linux kernel sources (under /usr/src). By default, /var hosts the Gentoo ebuild repository (located at /var/db/repos/gentoo) which, depending on the file system, generally consumes around 650 MiB of disk space. This space estimate excludes the /var/cache/distfiles and /var/cache/binpkgs directories, which will gradually fill with source files and (optionally) binary packages respectively as they are added to the system.

How many partitions and how big very much depends on considering the trade-offs and choosing the best option for the circumstance. 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 realized 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 certain disadvantages as well:

• If not configured properly, the system might have lots of free space on one partition and little free space on another.
• A separate partition for /usr/ may require the administrator to boot with an initramfs to mount the partition before other boot scripts start. Since the generation and maintenance of an initramfs is beyond the scope of this handbook, we recommend that newcomers do not use a separate partition for /usr/.
• There is also a 15-partition limit for SCSI and SATA unless the disk uses GPT labels.

What about swap space?[edit | edit source]

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 has lots of memory available, then it probably does not need much swap space. However, swap space is used to store the entire contents of memory in case of hibernation. If the system requires support for hibernation, then swap space larger than or equal to the amount of memory is necessary.

As a general rule of thumb, the swap space size is recommended to be twice the internal memory (RAM). For systems with multiple hard disks, it is wise to create one swap partition on each disk so that they can be utilized for parallel read/write operations. The faster a disk can swap, the faster the system will run when data in swap space must be accessed. When choosing between rotational and solid state disks, it is better for performance to put swap on the SSD. Also, swap files can be used as an alternative to swap partitions; this is mostly interesting for systems with very limited disk space.

What is the EFI System Partition (ESP)?[edit | edit source]

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 below contain the necessary pointers to correctly handle this operation. The EFI system partition is not required when booting in BIOS/Legacy mode.

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. After partitioning, format the ESP accordingly:

What is the BIOS boot partition?[edit | edit source]

A BIOS boot partition is only needed when combining a GPT partition layout with GRUB2 in BIOS/Legacy mode. It is not required when booting in EFI/UEFI mode, and also not required when using a MBR table. It 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. It will not be used in this guide.

Viewing the current partition layout[edit | edit source]

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

Use the p key to display the disk's current partition configuration:

Disk /dev/sda: 28.89 GiB, 31001149440 bytes, 60549120 sectors
Disk model: DataTraveler 2.0
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: 21AAD8CF-DB67-0F43-9374-416C7A4E31EA

Device        Start      End  Sectors  Size Type
/dev/sda1      2048   526335   524288  256M EFI System
/dev/sda2    526336  2623487  2097152    1G Linux swap
/dev/sda3   2623488 19400703 16777216    8G Linux filesystem
/dev/sda4  19400704 60549086 41148383 19.6G Linux filesystem

This particular disk was configured to house two Linux filesystems (each with a corresponding partition listed as "Linux") as well as a swap partition (listed as "Linux swap").

Creating a new disklabel / removing all partitions[edit | edit source]

Type g to create a new GPT disklabel on the disk; this will remove all existing partitions.

Created a new GPT disklabel (GUID: 87EA4497-2722-DF43-A954-368E46AE5C5F).

For an existing GPT disklabel (see the output of p above), alternatively consider removing the existing partitions one by one from the disk. Type d to delete a partition. For instance, to delete an existing /dev/sda1:

Partition number (1-4): 1

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: 28.89 GiB, 31001149440 bytes, 60549120 sectors
Disk model: DataTraveler 2.0
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: 87EA4497-2722-DF43-A954-368E46AE5C5F

Now that the in-memory partition table is empty, we're ready to create the partitions.

Creating the EFI system partition (ESP)[edit | edit source]

First create a small EFI system partition, which will also be mounted as /boot. Type n to create a new partition, followed by 1 to select the first partition. When prompted for the first sector, make sure it starts from 2048 (which may be needed for the boot loader) and hit Enter. When prompted for the last sector, type +256M to create a partition 256 Mbyte in size:

Partition number (1-128, default 1): 1
First sector (2048-60549086, default 2048): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (2048-60549086, default 60549086): +256M

Created a new partition 1 of type 'Linux filesystem' and of size 256 MiB.

Mark the partition as EFI system partition:

Selected partition 1
Partition type (type L to list all types): 1
Changed type of partition 'Linux filesystem' to 'EFI System'.

Creating the swap partition[edit | edit source]

Next, to create the swap partition, type n to create a new partition, then type 2 to create the second partition, /dev/sda2. When prompted for the first sector, hit Enter. When prompted for the last sector, type +4G (or any other size needed for the swap space) to create a partition 4GB in size.

Partition number (2-128, default 2): 
First sector (526336-60549086, default 526336): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (526336-60549086, default 60549086): +4G

Created a new partition 2 of type 'Linux filesystem' and of size 4 GiB.

After all this is done, type t to set the partition type, 2 to select the partition just created and then type in 19 to set the partition type to "Linux Swap".

Partition number (1,2, default 2): 2
Partition type (type L to list all types): 19

Changed type of partition 'Linux filesystem' to 'Linux swap'.

Creating the root partition[edit | edit source]

Finally, to create the root partition, type n to create a new partition. Then type 3 to create the third partition, /dev/sda3. 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:

Disk /dev/sda: 28.89 GiB, 31001149440 bytes, 60549120 sectors
Disk model: DataTraveler 2.0
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: 87EA4497-2722-DF43-A954-368E46AE5C5F

Device       Start      End  Sectors  Size Type
/dev/sda1     2048   526335   524288  256M EFI System
/dev/sda2   526336  8914943  8388608    4G Linux swap
/dev/sda3  8914944 60549086 51634143 24.6G Linux filesystem

Saving the partition layout[edit | edit source]

To save the partition layout and exit fdisk, type w.

With the partitions created, it is now time to put filesystems on them.

Viewing the current partition layout[edit | edit source]

Fire up fdisk against the disk (in our example, we use /dev/sda):

Use the p key to display the disk's current partition configuration:

Disk /dev/sda: 28.89 GiB, 31001149440 bytes, 60549120 sectors
Disk model: DataTraveler 2.0
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: 21AAD8CF-DB67-0F43-9374-416C7A4E31EA

Device        Start      End  Sectors  Size Type
/dev/sda1      2048   526335   524288  256M EFI System
/dev/sda2    526336  2623487  2097152    1G Linux swap
/dev/sda3   2623488 19400703 16777216    8G Linux filesystem
/dev/sda4  19400704 60549086 41148383 19.6G Linux filesystem

This particular disk was until now configured to house two Linux filesystems (each with a corresponding partition listed as "Linux") as well as a swap partition (listed as "Linux swap"), using a GPT table.

Creating a new disklabel / removing all partitions[edit | edit source]

Type o to create a new MBR disklabel (here also named DOS disklabel) on the disk; this will remove all existing partitions.

Created a new DOS disklabel with disk identifier 0xe04e67c4.
The device contains 'gpt' signature and it will be removed by a write command. See fdisk(8) man page and --wipe option for more details.

For an existing DOS disklabel (see the output of p above), alternatively consider removing the existing partitions one by one from the disk. Type d to delete a partition. For instance, to delete an existing /dev/sda1:

Partition number (1-4): 1

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: 28.89 GiB, 31001149440 bytes, 60549120 sectors
Disk model: DataTraveler 2.0
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0xe04e67c4

Now we're ready to create the partitions.

Creating the boot partition[edit | edit source]

First, create a small partition which will be mounted as /boot. Type n to create a new partition, followed by p for a primary partition and 1 to select the first primary partition. When prompted for the first sector, make sure it starts from 2048 (which may be needed for the boot loader) and hit Enter. When prompted for the last sector, type +256M to create a partition 256 Mbyte in size:

Partition type
   p   primary (0 primary, 0 extended, 4 free)
   e   extended (container for logical partitions)
Select (default p): p
Partition number (1-4, default 1): 1
First sector (2048-60549119, default 2048): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (2048-60549119, default 60549119): +256M

Created a new partition 1 of type 'Linux' and of size 256 MiB.

Creating the swap partition[edit | edit source]

Next, to create the swap partition, type n to create a new partition, then p, then type 2 to create the second primary partition, /dev/sda2. When prompted for the first sector, hit Enter. When prompted for the last sector, type +4G (or any other size needed for the swap space) to create a partition 4GB in size.

Partition type
   p   primary (1 primary, 0 extended, 3 free)
   e   extended (container for logical partitions)
Select (default p): p
Partition number (2-4, default 2): 2
First sector (526336-60549119, default 526336): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (526336-60549119, default 60549119): +4G

Created a new partition 2 of type 'Linux' and of size 4 GiB.

After all this is done, type t to set the partition type, 2 to select the partition just created and then type in 82 to set the partition type to "Linux Swap".

Partition number (1,2, default 2): 2
Hex code (type L to list all codes): 82

Changed type of partition 'Linux' to 'Linux swap / Solaris'.

Creating the root partition[edit | edit source]

Finally, to create the root partition, type n to create a new partition. Then type p and 3 to create the third primary partition, /dev/sda3. 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:

Disk /dev/sda: 28.89 GiB, 31001149440 bytes, 60549120 sectors
Disk model: DataTraveler 2.0
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0xe04e67c4

Device     Boot   Start      End  Sectors  Size Id Type
/dev/sda1          2048   526335   524288  256M 83 Linux
/dev/sda2        526336  8914943  8388608    4G 82 Linux swap / Solaris
/dev/sda3       8914944 60549119 51634176 24.6G 83 Linux

Saving the partition layout[edit | edit source]

To save the partition layout and exit fdisk, type w.

Now it is time to put filesystems on the partitions.

Introduction[edit | edit source]

Now that the partitions have been 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[edit | edit source]

Linux supports several dozen filesystems, although many of them are only wise to deploy for specific purposes. Only certain filesystems may be found found stable on the x86 architecture - it is advised to read up on the filesystems and their support state before selecting a more experimental one for important partitions. Ext4 is the recommended all-purpose all-platform filesystem.

btrfs

A next generation filesystem that provides many advanced features such as snapshotting, self-healing through checksums, transparent compression, subvolumes, and integrated RAID. Kernels prior to 5.4.y are not guaranteed to be safe to use with btrfs in production because fixes for serious issues are only present in the more recent releases of the LTS kernel branches. Filesystem corruption issues are common on older kernel branches, with anything older than 4.4.y being especially unsafe and prone to corruption. Corruption is more likely on older kernels (than 5.4.y) when compression is enabled. RAID 5/6 and quota groups unsafe on all versions of btrfs. Furthermore, btrfs can counter-intuitively fail filesystem operations with ENOSPC when df reports free space due to internal fragmentation (free space pinned by DATA + SYSTEM chunks, but needed in METADATA chunks). Additionally, a single 4K reference to a 128M extent inside btrfs can cause free space to be present, but unavailable for allocations. This can also cause btrfs to return ENOSPC when free space is reported by df. Installing sys-fs/btrfsmaintenance and configuring the scripts to run periodically can help to reduce the possibility of ENOSPC issues by rebalancing btrfs, but it will not eliminate the risk of ENOSPC when free space is present. Some workloads will never hit ENOSPC while others will. If the risk of ENOSPC in production is unacceptable, you should use something else. If using btrfs, be certain to avoid configurations known to have issues. With the exception of ENOSPC, information on the issues present in btrfs in the latest kernel branches is available at the btrfs wiki status page.

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 version 3 is included in the mainline Linux kernel, but is not recommended to be used when initially installing a Gentoo system. Newer versions of the ReiserFS filesystem exist, however they require additional patching of the mainline kernel to be utilized.

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, but has been continuously upgraded to include modern features.

VFAT

Also known as FAT32, is supported by Linux but does not support standard UNIX permission settings. It is mostly used for interoperability with other operating systems (Microsoft Windows or Apple's OSX) but is also a necessity for some system bootloader firmware (like UEFI).

NTFS

This "New Technology" filesystem is the flagship filesystem of Microsoft Windows since Windows NT 3.1. Similar to vfat above it does not store UNIX permission settings or extended attributes necessary for BSD or Linux to function properly, therefore it should not be used as a root filesystem. It should only be used for interoperability with Microsoft Windows systems (note the emphasis on only).

Applying a filesystem to a partition[edit | edit source]

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:

For instance, to have the EFI system partition partition (/dev/sda2) as FAT32 and the root partition (/dev/sda4) as ext4 as used in the example partition structure, the following commands would be used:

When using ext2, ext3, or ext4 on a small partition (less than 8 GiB), then the file system must be created with the proper options to reserve enough inodes. This can be done using one of the following commands, respectively:

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.

Now create the filesystems on the newly created partitions (or logical volumes).

Activating the swap partition[edit | edit source]

mkswap is the command that is used to initialize swap partitions:

To activate the swap partition, use swapon:

Create and activate the swap with the commands mentioned above.

Setting the date and time[edit | edit source]

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:

Mon Oct  3 13:16:22 PDT 2016

If the date/time displayed is wrong, update it using one of the methods below.

Choosing a stage tarball[edit | edit source]

Downloading the stage tarball[edit | edit source]

Go to the Gentoo mount point where the root file system is mounted (most likely /mnt/gentoo):

Depending on the installation medium, the only tool necessary to download a stage tarball is a web browser.

Unpacking the stage tarball[edit | edit source]

Now unpack the downloaded stage onto the system. We use tar to proceed:

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.

Introduction[edit | edit source]

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.

Fire up an editor (in this guide we use nano) to alter the optimization variables we will discuss hereafter.

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[edit | edit source]

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:

# Compiler flags to set for all languages
COMMON_FLAGS="-O2 -march=i686 -pipe"
# Use the same settings for both variables
CFLAGS="${COMMON_FLAGS}"
CXXFLAGS="${COMMON_FLAGS}"

MAKEOPTS[edit | edit source]

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.

MAKEOPTS="-j2"

Ready, set, go![edit | edit source]

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.

Optional: Selecting mirrors[edit | edit source]

[DEFAULT]
main-repo = gentoo
 
[gentoo]
location = /var/db/repos/gentoo
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

Copy DNS info[edit | edit source]

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

Mounting the necessary filesystems[edit | edit source]

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.

Entering the new environment[edit | edit source]

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.

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!

Mounting the boot partition

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

Installing a Gentoo ebuild repository snapshot from the web[edit | edit source]

Next step is to install a snapshot of the Gentoo 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 (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:

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 until after the Gentoo installation has finished.

Optional: Updating the Gentoo ebuild repository[edit | edit source]

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.

On slow terminals, like some framebuffers or serial consoles, it is recommended to use the --quiet option to speed up the process:

Reading news items[edit | edit source]

When the Gentoo ebuild repository is synchronized, Portage may output informational messages similar to the following:

News items were created to provide a communication medium to push critical messages to users via the Gentoo ebuild repository. To manage them, use eselect news. The eselect application is a Gentoo-specific utility that allows for a common management interface for system administration. 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.

More information about the news reader is available through its manual page:

Choosing the right profile[edit | edit source]

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:

Available profile symlink targets:
  [1]   default/linux/x86/ *
  [2]   default/linux/x86//desktop
  [3]   default/linux/x86//desktop/gnome
  [4]   default/linux/x86//desktop/kde

As can be seen, there are also desktop subprofiles available for some architectures.

After viewing the available profiles for the x86 architecture, users can select a different profile for the system:

Updating the @world set[edit | edit source]

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:

Configuring the USE variable[edit | edit source]

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:

USE="X acl alsa amd64 berkdb bindist bzip2 cli cracklib crypt cxx dri ..."

A full description on the available USE flags can be found on the system in /var/db/repos/gentoo/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:

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

USE="-* X acl alsa"

Optional: Configuring the ACCEPT_LICENSE variable[edit | edit source]

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:

Gentoo comes with a predefined value in the profiles, for example:

@FREE

This can be customized system wide by changing /etc/portage/make.conf. The default value will only accept licenses that are explicitly approved by the Free Software Foundation, the Open Source Initiative, or that follow the Free Software Definition:

ACCEPT_LICENSE="-* @FREE"

Per package overrides can then be added if necessary and desired, for example:

app-arch/unrar unRAR
sys-kernel/linux-firmware @BINARY-REDISTRIBUTABLE
sys-firmware/intel-microcode intel-ucode

Locale generation[edit | edit source]

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 the rules for sorting strings, displaying dates and times, etc. Locales are case sensitive and must be represented exactly as described. A full listing of available locales can be found in the /usr/share/i18n/SUPPORTED file.

Supported system locales must be defined in the /etc/locale.gen file.

The following locales are an example to get both English (United States) and German (Germany/Deutchland) with the accompanying character formats (like UTF-8).

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

The next step is to run the locale-gen command. This command generates all locales specified in the /etc/locale.gen file.

To verify that the selected locales are now available, run locale -a.

Locale selection[edit | edit source]

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:

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 <NUMBER> the correct locale can be selected:

Manually, this can still be accomplished through the /etc/env.d/02locale file:

LANG="de_DE.UTF-8"
LC_COLLATE="C"

Setting the locale will avoid warnings and errors during kernel and software compilations later in the installation.

Now reload the environment:

A full Localization guide to provide additional guidance through the locale selection process. Another interesting article is the UTF-8 guide for very specific information to enable UTF-8 on the system.

Introduction[edit | edit source]

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:

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.

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[edit | edit source]

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

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

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

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

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

Processor type and features  --->
  [*] Symmetric multi-processing support

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

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[edit | edit source]

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.

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

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

Processor type and features  --->
    [*] 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[edit | edit source]

With the configuration now done, it is time to compile and install the kernel. Exit the configuration and start the compilation process:

When the kernel has finished compiling, copy the kernel image to /boot/. This is handled by the make install command:

This will copy the kernel image into /boot/ together with the System.map file and the kernel configuration file.

Optional: Building an initramfs[edit | edit source]

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:

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

The initramfs will be stored in /boot/. The resulting file can be found by simply listing the files starting with initramfs:

Now continue with Kernel modules.

Installing correct installkernel[edit | edit source]

Before using the distribution kernels, please verify that you are using the correct installkernel package for your system. When using systemd-boot (formerly gummiboot), install:

When using a traditional /boot layout (e.g. GRUB, LILO, etc.), the gentoo variant should be installed by default. If in doubt:

Installing a distribution kernel[edit | edit source]

To build a kernel with Gentoo patches from source, type:

System administrators who want to avoid compiling the kernel sources locally can instead use precompiled kernel images:

Upgrading and cleaning up[edit | edit source]

Once the kernel is installed, the package manager will automatically upgrade it to newer versions. The previous versions will be kept until the package manager is requested to clean up stale packages. Please remember to periodically run:

to save space. Alternatively, to specifically clean up old kernel versions:

Post-install/upgrade tasks[edit | edit source]

Due to technical limitations, distribution kernels can not automatically rebuild kernel modules installed by other packages. Therefore, after kernel upgrade manually execute:

If any of these modules (e.g. ZFS) are needed at early boot, rebuild initramfs afterward:

Configuring the modules[edit | edit source]

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:

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.

3c59x

Continue the installation with Configuring the system.

Optional: Installing firmware[edit | edit source]

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:

About fstab[edit | edit source]

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[edit | edit source]

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

In the remainder of the text, we use the default /dev/sd* block device files as partition.

/dev/sda2   /boot     ext2    defaults        0 2

/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

Host and domain information[edit | edit source]

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.

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

# Set the dns_domain_lo variable to the selected domain name
dns_domain_lo="homenetwork"

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"

Configuring the network[edit | edit source]

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.

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:

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:

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:

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[edit | edit source]

To have the network interfaces activated at boot, they need to be added to the default runlevel.

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[edit | edit source]

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.

# 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[edit | edit source]

PCMCIA users should now install the sys-apps/pcmciautils package.

Root password[edit | edit source]

Set the root password using the passwd command.

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[edit | edit source]

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.

Next, open /etc/conf.d/keymaps to handle keyboard configuration. Edit it to configure and select the right keyboard.

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.

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.

Installing a DHCP client[edit | edit source]

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:

More information on dhcpcd can be found in the dhcpcd article.

Optional: Installing a PPPoE client[edit | edit source]

If PPP is used to connect to the internet, install the net-dialup/ppp package:

Optional: Install wireless networking tools[edit | edit source]

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.

Now continue with Configuring the bootloader.

Although installing for a 32-bit CPU, almost all x86 motherboards (starting from around 2006-2007 until the present) that were produced with support for UEFI have 64-bit UEFI firmware. Some users may notice "64" in the name of configuration settings and files in the coming sections below. This is expected in nearly every case.

There are a few very small exceptions to this 64-bit UEFI firmware rule, namely few early Apple Macs and some Intel Atom powered Dell tablet PCs had support for 32-bit UEFI firmware. The vast majority of readers will never encounter 32-bit UEFI firmware in the wild. For this reason 32-bit UEFI firmware is not covered in the x86 Handbook.

Emerge[edit | edit source]

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[edit | edit source]

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:

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[edit | edit source]

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:

Generating grub.cfg ...
Found linux image: /boot/vmlinuz-3.16.5-gentoo
Found initrd image: /boot/initramfs-genkernel-x86-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.

Emerge[edit | edit source]

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.

Configure[edit | edit source]

To configure LILO, first create /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.

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 on 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
  
image=/boot/vmlinuz-3.16.5-gentoo
  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

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:

image=/boot/vmlinuz-3.16.5-gentoo
  label=gentoo
  read-only
  append="root=/dev/sda4"
  initrd=/boot/initramfs-genkernel-x86-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:

image=/boot/vmlinuz-3.16.5-gentoo
  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[edit | edit source]

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.

Adding a user for daily use[edit | edit source]

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:

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:

Password: (Enter the root password)

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.

Removing tarballs[edit | edit source]

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.

Documentation[edit | edit source]

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[edit | edit source]

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.

Closing thoughts[edit | edit source]

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!