Handbook:Parts/Installation/Stage

Setting the date and time
Before installing Gentoo, it is a good idea to be sure the date and time are set correctly. A misconfigured clock may lead to strange issues with the installation: base system files should be extracted with accurate time stamps. In fact, due to Gentoo's web based services using security certificates, it might not be possible to download the installation files if the system clock is too far skewed. An accurate clock is a requirement for proceeding with the installation.

Verify the current date and time by running the command:

If the date/time displayed is more than few minutes off, it should be updated in accuracy using one of the methods below.

Automatic
Most readers will desire to have their system update the time automatically using a time server.

Official Gentoo live environments include the command (available through the  package) and a configuration file pointing to ntp.org time servers. It can be used to automatically sync the system clock to UTC time using a time server. Using this method requires a working network configuration and may not be available on all architectures.

Manual
For systems that do not have access to a time server, the command can also be used to set the system clock. It will use the following format as an argument:  syntax (Month, Day, hour, minute and Year).

UTC time is recommended for all Linux systems. A timezone will be defined later in the installation which will modify the clock to display local time.

For instance, to set the date to October 3rd, 13:16 in the year 2021, issue:

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

Most users should not use the 'advanced' tarballs options; they are for specific software or hardware configurations.

No-multilib (pure 64-bit)
Selecting a no-multilib tarball to be the base of the system provides a complete 64-bit operating system environment. This effectively renders the ability to switch to multilib profiles improbable, although still technically possible.

OpenRC
OpenRC is a dependency-based init system (responsible for starting up system services once the kernel has booted) that maintains compatibility with the system provided init program, normally located in. It is Gentoo's native and original init system, but is also deployed by a few other Linux distributions and BSD systems.

OpenRC does not function as a replacement for the file by default and is 100% compatible with Gentoo init scripts. This means a solution can be found to run the dozens of daemons in the Gentoo ebuild repository.

For historical reasons only, this manual focuses on installation and configuration using OpenRC. Rewriting and enhancing it to also explain a systemd installation (see below) is planned.

systemd
systemd is a modern SysV-style init and rc replacement for Linux systems. It is used as the primary init system by a majority of Linux distributions. systemd is fully supported in Gentoo and works for its intended purpose. Unfortunately, the corresponding installation Handbook sections for system still need to be written or are work in progress. It something seems lacking in the Handbook for a systemd install path, review the systemd article before asking for support.

Downloading the stage tarball
Go to the Gentoo mount point where the root file system is mounted (most likely ):

Graphical browsers
Those using environments with fully graphical web browsers will have no problem copying a stage file URL from the main website's download section. Simply select the appropriate tab, right click the link to the stage file, then to copy the link to the clipboard, then paste the link to the  utility on the command-line to download the stage tarball:

Command-line browsers
More traditional readers or 'old timer' Gentoo users, working exclusively from command-line may prefer using, a non-graphical, menu-driven browser. To download a stage, surf to the Gentoo mirror list like so:

To use an HTTP proxy with, pass on the URL with the  option:

Next to there is also the   browser. Like it is a non-graphical browser but it is not menu-driven.

If a proxy needs to be defined, export the http_proxy and/or ftp_proxy variables:

On the mirror list, select a mirror close by. Usually HTTP mirrors suffice, but other protocols are available as well. Move to the directory. There all available stage files are displayed (they might be stored within subdirectories named after the individual sub-architectures). Select one and press to download.

After the stage file download completes, it is possible to verify the integrity and validate the contents of the stage tarball. Those interested should proceed to the next section.

Those not interested in verifying and validating the stage file can close the command-line browser by pressing and can move directly to the Unpacking the stage tarball section.

Verifying and validating
Like with the minimal installation CDs, additional downloads to verify and validate the stage file are available. Although these steps may be skipped, these files are provided for users who care about the legitimacy of the file(s) they just downloaded.


 * A file that contains a list of all files inside the stage tarball.
 * A file that contains checksums of the stage file in different algorithms.
 * A file that, like the  file, contains checksums of the stage file in different algorithms, but is also cryptographically signed to ensure it is provided by the Gentoo project.

Use and compare the output with the checksums provided by the  or  files.

For instance, to validate the SHA512 checksum:

Another way is to use the command:

To validate the Whirlpool checksum:

Compare the output of these commands with the value registered in the files. The values need to match, otherwise the downloaded file might be corrupt (or the digests file is).

Just like with the ISO file, it is also possible to verify the cryptographic signature of the file using  to make sure the checksums have not been tampered with:

The fingerprints of the OpenPGP keys used for signing release media can be found on the release media signatures page of the Gentoo webserver.

Unpacking the stage tarball
Now unpack the downloaded stage onto the system. Use the utility to proceed:

Verity the same options ( and  ) are used in the command. The  stands for extract, the   for preserve permissions and the   to denote that we want to extract a file (not standard input). is to include preservation of the the extended attributes in all namespaces stored in the archive. Finally,  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 live environments).

Now that the stage file is unpacked, proceed with Configuring the compile options.

Introduction
To optimize the system, it is possible to set variables which impact the behavior of Portage, Gentoo's officially supported package manager. All those variables can be set as environment variables (using ) but setting via is not permanent.

Portage reads in the file when it runs, which will change runtime behavior depending on the values saved in the file. can be considered the primary configuration file for Portage, so treat its content carefully.

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

From the file it is obvious how the file should be structured: commented lines start with , other lines define variables using the   syntax. Several of those variables are discussed in the next section.

CFLAGS and CXXFLAGS
The CFLAGS and CXXFLAGS variables define the optimization flags for GCC C and C++ compilers respectively. Although those are defined generally here, for maximum performance one would need to optimize these flags for each program separately. The reason for this is because every program is different. However, this is not manageable, hence the definition of these flags in the file.

In 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 misbehave (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 ( - only works on a working Linux system). The file itself also contains lots of examples and information; don't forget to read it too.

A first setting is the  or   flag, which specifies the name of the target architecture. Possible options are described in the 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  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). is the recommended default. is known to cause problems when used system-wide, so we recommend to stick to.

Another popular optimization flag is  (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  (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:

MAKEOPTS
The MAKEOPTS variable defines how many parallel compilations should occur when installing a package. A good choice is the smaller of: the number of threads the CPU has, or the total system RAM divided by 2 GiB.

CPU_FLAGS_*
Some architectures (including AMD64/X86, ARM, PPC) have a USE_EXPAND variable called CPU_FLAGS_ARCH (replace ARCH as appropriate).

This is used to configure the build to compile in specific assembly code or other intrinsics, usually hand-written or otherwise extra, and is not the same as asking the compiler to output optimized code for a certain CPU feature.

A few steps are needed to set this up:

Inspect the output manually if curious:

Then copy the output into :

Ready, set, go!
Update the file to match personal preference and save (nano users would hit +).

Then continue with Installing the Gentoo base system.