From Gentoo Wiki
Jump to: navigation, search
Mlashley Handbook
About the installation
Choosing the media
Configuring the network
Preparing the disks
Installing stage3
Installing base system
Configuring the kernel
Configuring the system
Installing tools
Configuring the bootloader
Working with Gentoo
Portage introduction
USE flags
Portage features
Initscript system
Environment variables
Working with Portage
Files and directories
Mixing software branches
Additional tools
Custom package repository
Advanced features
Network configuration
Getting started
Advanced configuration
Modular networking
Adding functionality
Dynamic management



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

The Gentoo Installation can be seen as a 10-step procedure, corresponding to the next set of chapters. Each step results in a certain state:

Step Result
1 The user is in a working environment ready to install Gentoo.
2 The Internet connection is ready to install Gentoo.
3 The hard disks are initialized to host the Gentoo installation.
4 The installation environment is prepared and the user is ready to chroot into the new environment.
5 Core packages, which are the same on all Gentoo installations, are installed.
6 The Linux kernel is installed.
7 Most of the Gentoo system configuration files are created.
8 The necessary system tools are installed.
9 The proper boot loader has been installed and configured.
10 The freshly installed Gentoo Linux environment is ready to be explored.

Whenever a certain choice is presented the handbook will try to explain the pros and cons of each choice. Although the text then continues with a default choice (identified by "Default: " in the title), the other possibilities will be documented as well (marked by "Alternative: " in the title). Do not think that the default is what Gentoo recommends. It is, however, 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

Gentoo can be installed in many different ways. It can be downloaded and installed from official Gentoo installation media such as our CDs and DVDs. The installation media can be installed on a USB stick or accessed via a netbooted environment. Alternatively, Gentoo can be installed from non-official media such as an already installed distribution or a non-Gentoo bootable disk (such as Knoppix).

This document covers the installation using official Gentoo Installation media or, in certain cases, netbooting.

For help on the other installation approaches, including using non-Gentoo CDs, please read our Alternative installation guide.

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


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

Mlashley Handbook
About the installation
Choosing the media
Configuring the network
Preparing the disks
Installing stage3
Installing base system
Configuring the kernel
Configuring the system
Installing tools
Configuring the bootloader
Working with Gentoo
Portage introduction
USE flags
Portage features
Initscript system
Environment variables
Working with Portage
Files and directories
Mixing software branches
Additional tools
Custom package repository
Advanced features
Network configuration
Getting started
Advanced configuration
Modular networking
Adding functionality
Dynamic management

Hardware requirements

Before we start, we first list what hardware requirements are needed to successfully install Gentoo on a box.


Gentoo Linux installation media

Minimal installation CD

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--minimal-<release>.iso.

The occasional Gentoo LiveDVD

Occasionally, a special DVD is crafted by the Gentoo Ten project which can be used to install Gentoo. The instructions 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?

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. While Gentoo still offers stage1 and stage2 tarballs, this official installation method uses the stage3 tarball. Those interested in performing a Gentoo installation using a stage less than three should read the Gentoo FAQ on How do I install Gentoo using a stage1 or stage2 tarball?

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


Obtain the media

The default installation media that Gentoo Linux uses are the minimal installation CDs, which host a bootable, very small Gentoo Linux environment. This environment contains all the right tools to install Gentoo. The CD images themselves can be downloaded from the downloads page (recommended) or by manually browsing to the ISO location on one of the many available mirrors.

If downloading from a mirror, the minimal installation CDs can be found as follows:

  1. Go to the releases/ directory.
  2. Select the directory for the relevant target architecture (such as /).
  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.
Some target architectures such as arm, mips, and s390 will not have minimal install CDs. At this time the Gentoo Release Engineering project does not support building .iso files for these targets.

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

CODE Example list of downloadable files at releases//autobuilds/current-iso/
[DIR] hardened/                                          05-Dec-2014 01:42    -   
[   ] install--minimal-20141204.iso                 04-Dec-2014 21:04  208M  
[   ] install--minimal-20141204.iso.CONTENTS        04-Dec-2014 21:04  3.0K  
[   ] install--minimal-20141204.iso.DIGESTS         04-Dec-2014 21:04  740   
[TXT] install--minimal-20141204.iso.DIGESTS.asc     05-Dec-2014 01:42  1.6K  
[   ] stage3--20141204.tar.bz2                      04-Dec-2014 21:04  198M  
[   ] stage3--20141204.tar.bz2.CONTENTS             04-Dec-2014 21:04  4.6M  
[   ] stage3--20141204.tar.bz2.DIGESTS              04-Dec-2014 21:04  720   
[TXT] stage3--20141204.tar.bz2.DIGESTS.asc          05-Dec-2014 01:42  1.5K

In the above example, the install--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

This is an optional step and not necessary to install Gentoo Linux. However, it is recommended as it ensures that the downloaded file is not corrupt and has indeed been provided by the Gentoo Infrastructure team.

Through the .DIGESTS and .DIGESTS.asc files, the validity of the ISO file can be confirmed using the right set of tools. This verification is usually done in two steps:

  1. First, the cryptographic signature is validated to make sure that the installation file is provided by the Gentoo Release Engineering team
  2. If the cryptographic signature validates, then the checksum is verified to make sure that the downloaded file itself is not corrupted

Microsoft Windows based verification

On a Microsoft Windows system, chances are low that the right set of tools to verify checksums and cryptographic signatures are in place.

To first verify the cryptographic signature, tools such as GPG4Win can be used. After installation, the public keys of the Gentoo Release Engineering team need to be imported. The list of keys is available on the signatures page. Once imported, the user can then verify the signature of the .DIGESTS.asc file.

This does not verify that the .DIGESTS file is correct, only that the .DIGESTS.asc file is. That also implies that the checksum should be verified against the values in the .DIGESTS.asc file, which is why the instructions above only refer to downloading the .DIGESTS.asc file.

The checksum itself can be verified using the Hashcalc application, although many others exist as well. Most of the time, these tools will show the user the calculated checksum, and the user is requested to verify this checksum with the value that is inside the .DIGESTS.asc file.

Linux based verification

On a Linux system, the most common method for verifying the cryptographic signature is to use the app-crypt/gnupg software. With this package installed, the following commands can be used to verify the cryptographic signature of the .DIGESTS.asc file.

First, download the right set of keys as made available on the signatures page:

user $gpg --keyserver hkps:// --recv-keys 0xBB572E0E2D182910
gpg: requesting key 0xBB572E0E2D182910 from hkp server
gpg: key 0xBB572E0E2D182910: "Gentoo Linux Release Engineering (Automated Weekly Release Key) <>" 1 new signature
gpg: 3 marginal(s) needed, 1 complete(s) needed, classic trust model
gpg: depth: 0  valid:   3  signed:  20  trust: 0-, 0q, 0n, 0m, 0f, 3u
gpg: depth: 1  valid:  20  signed:  12  trust: 9-, 0q, 0n, 9m, 2f, 0u
gpg: next trustdb check due at 2018-09-15
gpg: Total number processed: 1
gpg:         new signatures: 1

Alternatively you can use instead the WKD to download the key:

--2019-04-19 20:46:32--
Resolving (
Connecting to (||: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) <>" 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) <>" imported
gpg: Total number processed: 2
gpg:               imported: 2
gpg: no ultimately trusted keys found

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

user $gpg --verify install--minimal-20141204.iso.DIGESTS.asc
gpg: Signature made Fri 05 Dec 2014 02:42:44 AM CET
gpg:                using RSA key 0xBB572E0E2D182910
gpg: Good signature from "Gentoo Linux Release Engineering (Automated Weekly Release Key) <>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 13EB BDBE DE7A 1277 5DFD  B1BA BB57 2E0E 2D18 2910

To be absolutely certain that everything is valid, verify the fingerprint shown with the fingerprint on the Gentoo signatures page.

With the cryptographic signature validated, next verify the checksum to make sure the downloaded ISO file is not corrupted. The .DIGESTS.asc file contains multiple hashing algorithms, so one of the methods to validate the right one is to first look at the checksum registered in the .DIGESTS.asc file. For instance, to get the SHA512 checksum:

user $grep -A 1 -i sha512 install--minimal-20141204.iso.DIGESTS.asc
364d32c4f8420605f8a9fa3a0fc55864d5b0d1af11aa62b7a4d4699a427e5144b2d918225dfb7c5dec8d3f0fe2cddb7cc306da6f0cef4f01abec33eec74f3024  install--minimal-20141204.iso
0719a8954dc7432750de2e3076c8b843a2c79f5e60defe43fcca8c32ab26681dfb9898b102e211174a895ff4c8c41ddd9e9a00ad6434d36c68d74bd02f19b57f  install--minimal-20141204.iso.CONTENTS

In the above output, two SHA512 checksums are shown - one for the install--minimal-20141204.iso file and one for its accompanying .CONTENTS file. Only the first checksum is of interest, as it needs to be compared with the calculated SHA512 checksum which can be generated as follows:

user $sha512sum install--minimal-20141204.iso
364d32c4f8420605f8a9fa3a0fc55864d5b0d1af11aa62b7a4d4699a427e5144b2d918225dfb7c5dec8d3f0fe2cddb7cc306da6f0cef4f01abec33eec74f3024  install--minimal-20141204.iso

As both checksums match, the file is not corrupted and the installation can continue.

Burning a disk

Of course, with just an ISO file downloaded, the Gentoo Linux installation cannot be started. The ISO file needs to be burned on a CD to boot from, and in such a way that its content is burned on the CD, not just the file itself. Below a few common methods are described - a more elaborate set of instructions can be found in Our FAQ on burning an ISO file.

Burning with Microsoft Windows 7 and above

Versions of Microsoft Windows 7 and above can both mount and burn ISO images to optical media without the requirement for third-party software. Simply insert a burnable disk, browse to the downloaded ISO files, right click the file in Windows Explorer, and select "Burn disk image".

Burning with Linux

The cdrecord utility from the package app-cdr/cdrtools can burn ISO images on Linux.

To burn the ISO file on the CD in the /dev/sr0 device (this is the first CD device on the system - substitute with the right device file if necessary):

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

Users that prefer a graphical user interface can use K3B, part of the kde-apps/k3b package. In K3B, go to Tools and use Burn CD Image.



Extra hardware configuration

When the Installation medium boots, it tries to detect all the hardware devices and loads the appropriate kernel modules to support the hardware. In the vast majority of cases, it does a very good job. However, in some cases it may not auto-load the kernel modules needed by the system. If the PCI auto-detection missed some of the system's hardware, the appropriate kernel modules have to be loaded manually.

In the next example the 8139too module (which supports certain kinds of network interfaces) is loaded:

root #modprobe 8139too

Optional: User accounts

If other people need access to the installation environment, or there is need to run commands as a non-root user on the installation medium (such as to chat using irssi without root privileges for security reasons), then an additional user account needs to be created and the root password set to a strong password.

To change the root password, use the passwd utility:

root #passwd
New password: (Enter the new password)
Re-enter password: (Re-enter the password)

To create a user account, first enter their credentials, followed by the account's password. The useradd and passwd commands are used for these tasks.

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

root #useradd -m -G users john
root #passwd john
New password: (Enter john's password)
Re-enter password: (Re-enter john's password)

To switch from the (current) root user to the newly created user account, use the su command:

root #su - john

Optional: Viewing documentation while installing


To view the Gentoo handbook during the installation, first create a user account as described above. Then press Alt+F2 to go to a new terminal.

During the installation, the links command can be used to browse the Gentoo handbook - of course only from the moment that the Internet connection is working.

user $links

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

GNU Screen

The Screen utility is installed by default on official Gentoo installation media. It may be more efficient for the seasoned Linux enthusiast to use screen to view installation instructions via split panes rather than the multiple TTY method mentioned above.

Optional: Starting the SSH daemon

To allow other users to access the system during the installation (perhaps to support during an installation, or even do it remotely), a user account needs to be created (as was documented earlier on) and the SSH daemon needs to be started.

To fire up the SSH daemon on an OpenRC init, execute the following command:

root #rc-service sshd start
If users log on to the system, they will see a message that the host key for this system needs to be confirmed (through what is called a fingerprint). This behavior is typical and can be expected for initial connections to an SSH server. However, later when the system is set up and someone logs on to the newly created system, the SSH client will warn that the host key has been changed. This is because the user now logs on to - for SSH - a different server (namely the freshly installed Gentoo system rather than the live environment that the installation is currently using). Follow the instructions given on the screen then to replace the host key on the client system.

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

Mlashley Handbook
About the installation
Choosing the media
Configuring the network
Preparing the disks
Installing stage3
Installing base system
Configuring the kernel
Configuring the system
Installing tools
Configuring the bootloader
Working with Gentoo
Portage introduction
USE flags
Portage features
Initscript system
Environment variables
Working with Portage
Files and directories
Mixing software branches
Additional tools
Custom package repository
Advanced features
Network configuration
Getting started
Advanced configuration
Modular networking
Adding functionality
Dynamic management

Automatic network detection

Maybe it just works?

If the system is plugged into an Ethernet network with a DHCP server, it is very likely that the networking configuration has already been set up automatically. If so, then the many included network-aware commands on the installation CD such as ssh, scp, ping, irssi, wget, and links, among others, will work immediately.

Determine interface names

ifconfig command

If networking has been configured, the ifconfig command should list one or more network interfaces (besides lo). In the example below eth0 shows up:

root #ifconfig
eth0      Link encap:Ethernet  HWaddr 00:50:BA:8F:61:7A
          inet addr:  Bcast:  Mask:
          inet6 addr: fe80::50:ba8f:617a/10 Scope:Link
          RX packets:1498792 errors:0 dropped:0 overruns:0 frame:0
          TX packets:1284980 errors:0 dropped:0 overruns:0 carrier:0
          collisions:1984 txqueuelen:100
          RX bytes:485691215 (463.1 Mb)  TX bytes:123951388 (118.2 Mb)
          Interrupt:11 Base address:0xe800 

As a result of the shift towards predictable network interface names, the interface name on the system can be quite different from the old eth0 naming convention. Recent installation media might show regular network interfaces names like eno0, ens1, or enp5s0. Look for the interface in the ifconfig output that has an IP address related to the local network.

If no interfaces are displayed when the standard ifconfig command is used, try using the same command with the -a option. This option forces the utility to show all network interfaces detected by the system whether they be in an up or down state. If ifconfig -a produces no results then the hardware is faulty or the driver for the interface has not been loaded into the kernel. Both situations reach beyond the scope of this Handbook. Contact #gentoo for support.

ip command

As an alternative to ifconfig, the ip command can be used to determine interface names. The following example shows the output of ip addr (of another system so the information shown is different from the previous example):

root #ip addr
2: eno1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether e8:40:f2:ac:25:7a brd ff:ff:ff:ff:ff:ff
    inet brd scope global eno1
       valid_lft forever preferred_lft forever
    inet6 fe80::ea40:f2ff:feac:257a/64 scope link 
       valid_lft forever preferred_lft forever

The output above may be a bit more complicated to read than alternative. The interface name in the above example directly follows the number; it is eno1.

In the remainder of this document, the handbook will assume that the operating network interface is called eth0.

Optional: Configure any proxies

If the Internet is accessed through a proxy, then it is necessary to set up proxy information during the installation. It is very easy to define a proxy: just define a variable which contains the proxy server information.

In most cases, it is sufficient to define the variables using the server hostname. As an example, we assume the proxy is called and the port is 8080.

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

root #export http_proxy=""

To set up an FTP proxy:

root #export ftp_proxy=""

To set up an RSYNC proxy:

root #export RSYNC_PROXY=""

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

CODE Adding username/password to the proxy variable

Testing the network

Try pinging your ISP's DNS server (found in /etc/resolv.conf) and a web site of choice. This ensures that the network is functioning properly and that the network packets are reaching the net, DNS name resolution is working correctly, etc.

root #ping -c 3

If this all works, then the remainder of this chapter can be skipped to jump right to the next step of the installation instructions (Preparing the disks).

Automatic network configuration

If the network doesn't work immediately, some installation media allow the user to use net-setup (for regular or wireless networks), pppoe-setup (for ADSL users) or pptp (for PPTP users).

If the installation medium does not contain any of these tools, continue with the Manual network configuration.

Default: Using net-setup

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

root #net-setup eth0

net-setup will ask some questions about the network environment. When all is done, the network connection should work. Test the network connection as stated before. If the tests are positive, congratulations! Skip the rest of this section and continue with Preparing the disks.

If the network still doesn't work, continue with Manual network configuration.

Alternative: Using PPP

Assuming PPPoE is needed to connect to the Internet, the installation CD (any version) has made things easier by including ppp. Use the provided pppoe-setup script to configure the connection. During the setup the Ethernet device that is connected to your ADSL modem, the username and password, the IPs of the DNS servers and if a basic firewall is needed or not will be asked.

root #pppoe-setup
root #pppoe-start

If something goes wrong, double-check that the username and password are correct by looking at etc/ppp/pap-secrets or /etc/ppp/chap-secrets and make sure to use the right Ethernet device. If the Ethernet device does not exist, the appropriate network modules need to be loaded. In that case continue with Manual network configuration as it will explain how to load the appropriate network modules there.

If everything worked, continue with Preparing the disks.

Alternative: Using PPTP

If PPTP support is needed, use pptpclient which is provided by the installation CDs. But first make sure that the configuration is correct. Edit /etc/ppp/pap-secrets or /etc/ppp/chap-secrets so it contains the correct username/password combination:

root #nano -w /etc/ppp/chap-secrets

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

root #nano -w /etc/ppp/options.pptp

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

root #pptp <server ipv4 address>

Now continue with Preparing the disks.

Manual network configuration

Loading the appropriate network modules

When the Installation CD boots, it tries to detect all the hardware devices and loads the appropriate kernel modules (drivers) to support the hardware. In the vast majority of cases, it does a very good job. However, in some cases, it may not auto-load the kernel modules needed.

If net-setup or pppoe-setup failed, then it is possible that the network card wasn't found immediately. This means users may have to load the appropriate kernel modules manually.

To find out what kernel modules are provided for networking, use the ls command:

root #ls /lib/modules/`uname -r`/kernel/drivers/net

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

root #modprobe pcnet32

To check if the network card is now detected, use ifconfig. A detected network card would result in something like this (again, eth0 here is just an example):

root #ifconfig eth0
eth0      Link encap:Ethernet  HWaddr FE:FD:00:00:00:00  
          BROADCAST NOARP MULTICAST  MTU:1500  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0 
          RX bytes:0 (0.0 b)  TX bytes:0 (0.0 b)

If however the following error is shown, the network card is not detected:

root #ifconfig eth0
eth0: error fetching interface information: Device not found

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

root #ls /sys/class/net
dummy0  eth0  lo  sit0  tap0  wlan0

In the above example, 6 interfaces are found. The eth0 one is most likely the (wired) Ethernet adapter whereas wlan0 is the wireless one.

Assuming that the network card is now detected, retry net-setup or pppoe-setup again (which should work now), but for the hardcore people we explain how to configure the network manually as well.

Select one of the following sections based on your network setup:

Using DHCP

DHCP (Dynamic Host Configuration Protocol) makes it possible to automatically receive networking information (IP address, netmask, broadcast address, gateway, nameservers etc.). This only works if a DHCP server is in the network (or if the ISP provider provides a DHCP service). To have a network interface receive this information automatically, use dhcpcd:

root #dhcpcd eth0

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

root #dhcpcd -HD eth0

If this works (try pinging some Internet server, like Google's or Cloudflare's, then everything is set and ready to continue. Skip the rest of this section and continue with Preparing the disks.

Preparing for wireless access

Support for the iw command might be architecture-specific. If the command is not available see if the net-wireless/iw package is available for the current architecture. The iw command will be unavailable unless the net-wireless/iw package has been installed.

When using a wireless (802.11) card, the wireless settings need to be configured before going any further. To see the current wireless settings on the card, one can use iw. Running iw might show something like:

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

To check for a current connection:

root #iw dev wlp9s0 link
Not connected.


root #iw dev wlp9s0 link
Connected to 00:00:00:00:00:00 (on wlp9s0)
	SSID: GentooNode
	freq: 2462
	RX: 3279 bytes (25 packets)
	TX: 1049 bytes (7 packets)
	signal: -23 dBm
	tx bitrate: 1.0 MBit/s
Some wireless cards may have a device name of wlan0 or ra0 instead of wlp9s0. Run ip link to determine the correct device name.

For most users, there are only two settings needed to connect, the ESSID (aka wireless network name) and, optionally, the WEP key.

  • First, ensure the interface is active:
root #ip link set dev wlp9s0 up
  • To connect to an open network with the name GentooNode:
root #iw dev wlp9s0 connect -w GentooNode
  • To connect with a hex WEP key, prefix the key with d::
root #iw dev wlp9s0 connect -w GentooNode key 0:d:1234123412341234abcd
  • To connect with an ASCII WEP key:
root #iw dev wlp9s0 connect -w GentooNode key 0:some-password
If the wireless network is set up with WPA or WPA2, then wpa_supplicant needs to be used. For more information on configuring wireless networking in Gentoo Linux, please read the Wireless networking chapter in the Gentoo Handbook.

Confirm the wireless settings by using iw dev wlp9s0 link. Once wireless is working, continue configuring the IP level networking options as described in the next section (Understanding network terminology) or use the net-setup tool as described previously.

Understanding network terminology

If the IP address, broadcast address, netmask and nameservers are known, then skip this subsection and continue with Using ifconfig and route.

If all of the above fails, the network will need to be configured manually. This is not difficult at all. However, some knowledge of network terminology and basic concepts might be necessary. After reading this section, users will know what a gateway is, what a netmask serves for, how a broadcast address is formed and why systems need nameservers.

In a network, hosts are identified by their IP address (Internet Protocol address). Such an address is perceived as a combination of four numbers between 0 and 255. Well, at least when using IPv4 (IP version 4). In reality, such an IPv4 address consists of 32 bits (ones and zeros). Let's view an example:

CODE Example of an IPv4 address
IP Address (numbers):
IP Address (bits):      11000000 10101000 00000000 00000010
                        -------- -------- -------- --------
                           192      168       0        2
The successor of IPv4, IPv6, uses 128 bits (ones and zeros). In this section, the focus is on IPv4 addresses.

Such an IP address is unique to a host as far as all accessible networks are concerned (i.e. every host that one wants to be able to reach must have a unique IP address). In order to distinguish between hosts inside and outside a network, the IP address is divided in two parts: the network part and the host part.

The separation is written down with the netmask, a collection of ones followed by a collection of zeros. The part of the IP that can be mapped on the ones is the network-part, the other one is the host-part. As usual, the netmask can be written down as an IP address.

CODE Example of network/host separation
IP address:    192      168      0         2
            11000000 10101000 00000000 00000010
Netmask:    11111111 11111111 11111111 00000000
               255      255     255        0
                    Network              Host

In other words, is part of the example network, but is not.

The broadcast address is an IP address with the same network-part as the network, but with only ones as host-part. Every host on the network listens to this IP address. It is truly meant for broadcasting packets.

CODE Broadcast address
IP address:    192      168      0         2
            11000000 10101000 00000000 00000010
Broadcast:  11000000 10101000 00000000 11111111
               192      168      0        255
                     Network             Host

To be able to surf on the Internet, each computer in the network must know which host shares the Internet connection. This host is called the gateway. Since it is a regular host, it has a regular IP address (for instance

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 to an IP address (such as Such a service is called a name service. To use such a service, the necessary name servers need to be defined in /etc/resolv.conf.

In some cases, the gateway also serves as a nameserver. Otherwise the nameservers provided by the ISP need to be entered in this file.

To summarize, the following information is needed before continuing:

Network item Example
The system IP address

Using ifconfig and route

Setting up the network consists of three steps:

  1. Assign an IP address using ifconfig
  2. Set up routing to the gateway using route
  3. Finish up by placing the nameserver IPs in /etc/resolv.conf

To assign an IP address, the IP address, broadcast address and netmask are needed. Then execute the following command, substituting ${IP_ADDR} with the right IP address, ${BROADCAST} with the right broadcast address and ${NETMASK} with the right netmask:

root #ifconfig eth0 ${IP_ADDR} broadcast ${BROADCAST} netmask ${NETMASK} up

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

root #route add default gw ${GATEWAY}

Now open /etc/resolv.conf:

root #nano -w /etc/resolv.conf

Fill in the nameserver(s) using the following as a template. Make sure to substitute ${NAMESERVER1} and ${NAMESERVER2} with the appropriate nameserver addresses:

FILE /etc/resolv.confDefault resolv.conf template
nameserver ${NAMESERVER1}
nameserver ${NAMESERVER2}

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

Mlashley Handbook
About the installation
Choosing the media
Configuring the network
Preparing the disks
Installing stage3
Installing base system
Configuring the kernel
Configuring the system
Installing tools
Configuring the bootloader
Working with Gentoo
Portage introduction
USE flags
Portage features
Initscript system
Environment variables
Working with Portage
Files and directories
Mixing software branches
Additional tools
Custom package repository
Advanced features
Network configuration
Getting started
Advanced configuration
Modular networking
Adding functionality
Dynamic management

Introduction to block devices

Block devices

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

To begin, let's look at block devices. The most famous block device is probably the one that represents the first drive in a Linux system, namely /dev/sda. SCSI and Serial ATA drives are both labeled /dev/sd*. On modern machines, PCI-Express based NVMe solid state disks have a unique block device schema such as, e.g., /dev/nvme0n1.

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 512-byte blocks.


Creating file systems


Now that the partitions are created, it is time to place a filesystem on them. In the next section the various file systems that Linux supports are described. Readers that already know which filesystem to use can continue with Applying a filesystem to a partition. The others should read on to learn about the available filesystems...


Several filesystems are available. Some of them are found stable on the architecture - it is advised to read up on the filesystems and their support state before selecting a more experimental one for important partitions.

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.
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.
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.
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.
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.
IBM's high-performance journaling filesystem. JFS is a light, fast, and reliable B+tree-based filesystem with good performance in various conditions.
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.
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.
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).
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).

When using ext2, ext3, or ext4 on a small partition (less than 8GB), then the file system must be created with the proper options to reserve enough inodes. The mke2fs (mkfs.ext2) application uses the "bytes-per-inode" setting to calculate the number of inodes for a file system. On smaller partitions, it is advised to increase the calculated number of inodes.

On ext2, ext3 and ext4, this can be done using one of the following commands, respectively:

root #mkfs.ext2 -T small /dev/<device>
root #mkfs.ext3 -T small /dev/<device>
root #mkfs.ext4 -T small /dev/<device>

This will generally quadruple the number of inodes for a given file system as its "bytes-per-inode" reduces from one every 16kB to one every 4kB. This can be tuned even further by providing the ratio:

root #mkfs.ext2 -i <ratio> /dev/<device>

Applying a filesystem to a partition

To create a filesystem on a partition or volume, there are user space utilities available for each possible filesystem. Click the filesystem's name in the table below for additional information on each filesystem:

Filesystem Creation command On minimal CD? Package
btrfs mkfs.btrfs Yes sys-fs/btrfs-progs
ext2 mkfs.ext2 Yes sys-fs/e2fsprogs
ext3 mkfs.ext3 Yes sys-fs/e2fsprogs
ext4 mkfs.ext4 Yes sys-fs/e2fsprogs
f2fs mkfs.f2fs Yes sys-fs/f2fs-tools
jfs mkfs.jfs Yes sys-fs/jfsutils
reiserfs mkfs.reiserfs Yes sys-fs/reiserfsprogs
xfs mkfs.xfs Yes sys-fs/xfsprogs
vfat mkfs.vfat Yes sys-fs/dosfstools
NTFS mkfs.ntfs Yes sys-fs/ntfs3g

For instance, to have the root partition () in ext4 as used in the example partition structure, the following commands would be used:

root #mkfs.ext4

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

Activating the swap partition

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

root #mkswap

To activate the swap partition, use swapon:

root #swapon

Create and activate the swap with the commands mentioned above.

Mounting the root partition

Now that the partitions are initialized and are housing a filesystem, it is time to mount those partitions. Use the mount command, but don't forget to create the necessary mount directories for every partition created. As an example we mount the root partition:

root #mount /mnt/gentoo
If /tmp/ needs to reside on a separate partition, be sure to change its permissions after mounting:
root #chmod 1777 /mnt/gentoo/tmp
This also holds for /var/tmp.

Later in the instructions the proc filesystem (a virtual interface with the kernel) as well as other kernel pseudo-filesystems will be mounted. But first we install the Gentoo installation files.