User:Zulu Foxtrott/Parts/Installation/Stage

From Gentoo Wiki
Jump to:navigation Jump to:search

{{Handbook:Parts/TOC}}

Installing a stage tarball

Setting the date and time

Before installing Gentoo, it is a good idea to be sure the date and time are set correctly. A mis-configured clock may lead to strange results: base system files should be extracted with accurate time stamps. In fact, due to several websites and services using encrypted communications (SSL/TLS), it might not be possible to download the installation files at all if the system clock is too far skewed!

Verify the current date and time by running the date command:

root #date
Mon Oct  3 13:16:22 PDT 2016

If the date/time displayed is wrong, update it using the method outlined below.

Note
Motherboards that do not include a Real-Time Clock (RTC) should be configured to automatically sync the system clock with a time server. This is also true for systems that do include a RTC, but have a failed battery.

Manual update

The date command can also be used to perform a manual set on the system clock. Use the MMDDhhmmYYYY syntax (Month, Day, hour, minute and Year).

UTC time is recommended for all Linux systems. Later on during the installation a timezone will be defined. This will modify the display of the clock to local time.

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

root #date 100313162016

Choosing a stage tarball

Multilib (32 and 64-bit)

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

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

No-multilib (pure 64-bit)

Selecting a no-multilib tarball to be the base of the system provides a complete 64-bit operating system environment. This effectively renders the ability to switch to multilib profiles improbable, but possible. Those who are just starting out with Gentoo should not choose a no-multilib tarball unless it is absolutely necessary.

Warning
Be aware, migrating from a no-multilib to a multilib system requires an extremely well-working knowledge of Gentoo and the lower-level toolchain (it may even cause our Toolchain developers to shudder a little). It is not for the faint of heart and is beyond the scope of this guide.

{{Handbook:Zulu Foxtrott/Blocks/Stage}}

Downloading the stage tarball

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

root #cd /mnt/gentoo

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

Graphical browsers

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

root #wget <PASTED_STAGE_URL>

Command-line browsers

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

root #links https://www.gentoo.org/downloads/mirrors/

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

root #links -http-proxy proxy.server.com:8080 https://www.gentoo.org/downloads/mirrors/

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

root #lynx https://www.gentoo.org/downloads/mirrors/

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

root #export http_proxy="http://proxy.server.com:port"
root #export ftp_proxy="http://proxy.server.com:port"

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

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

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

Verifying and validating

Note
Some tarballs are being delivered via xz compression. When downloading a tarball ending in .tar.xz, be sure to adjust the tarball filename from .tar.bz2 in the following commands.

Additional downloads to verify and validate the stage file are available. Although these steps may be skipped, these files are provided for users who care about the legitimacy of the file(s) they just downloaded.

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

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

For instance, to validate the SHA512 checksum:

root #openssl dgst -r -sha512 stage3--<release>.tar.?(bz2|xz)

Another way is to use the sha512sum command:

root #sha512sum stage3--<release>.tar.?(bz2|xz)

To validate the Whirlpool checksum:

root #openssl dgst -r -whirlpool stage3--<release>.tar.?(bz2|xz)

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

It's also possible to verify the cryptographic signature of the .DIGESTS.asc file using gpg to make sure the checksums have not been tampered with:

root #gpg --verify stage3--<release>.tar.?(bz2|xz){.DIGESTS.asc,}

Unpacking the stage tarball

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

root #tar xpvf --xattrs-include='*.*' --numeric-owner

Make sure that the same options (xpf and --xattrs-include='*.*') are used. The x stands for extract, the p for preserve permissions and the f to denote that we want to extract a file (not standard input). --xattrs-include='*.*' is to include preservation of the the extended attributes in all namespaces stored in the archive. Finally, --numeric-owner is used to ensure that the user and group IDs of the files being extracted from the tarball will remain the same as Gentoo's release engineering team intended (even if adventurous users are not using official Gentoo installation media).

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

Configuring compile options

Introduction

To optimize Gentoo, it is possible to set a couple of variables which impacts the behavior of Portage, Gentoo's officially supported package manager. All those variables can be set as environment variables (using export) but that isn't permanent. To keep the settings, Portage reads in the /etc/portage/make.conf file, a configuration file for Portage.

Note
A commented listing of all possible variables can be found in /mnt/gentoo/usr/share/portage/config/make.conf.example. For a successful Gentoo installation only the variables that are mentioned below need to be set.

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

root #nano -w /mnt/gentoo/etc/portage/make.conf

From the make.conf.example file it is obvious how the file should be structured: commented lines start with "#", other lines define variables using the VARIABLE="content" syntax. Several of those variables are discussed next.

CFLAGS and CXXFLAGS

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

In make.conf one should define the optimization flags that will make the system the most responsive generally. Don't place experimental settings in this variable; too much optimization can make programs behave bad (crash, or even worse, malfunction).

We will not explain all possible optimization options. To understand them all, read the GNU Online Manual(s), the gcc info page (info gcc - only works on a working Linux system) or the gcc man-page (man gcc). The make.conf.example file itself also contains lots of examples and information; don't forget to read it too.

A first setting is the -march= or -mtune= flag, which specifies the name of the target architecture. Possible options are described in the make.conf.example file (as comments). A commonly used value is native as that tells the compiler to select the target architecture of the current system (the one users are installing Gentoo on).

A second one is the -O flag (that is a capital O, not a zero), which specifies the gcc optimization class flag. Possible classes are s (for size-optimized), 0 (zero - for no optimizations), 1, 2 or even 3 for more speed-optimization flags (every class has the same flags as the one before, plus some extras). -O2 is the recommended default. -O3 is known to cause problems when used system-wide, so we recommend to stick to -O2.

Another popular optimization flag is -pipe (use pipes rather than temporary files for communication between the various stages of compilation). It has no impact on the generated code, but uses more memory. On systems with low memory, gcc might get killed. In that case, do not use this flag.

Using -fomit-frame-pointer (which doesn't keep the frame pointer in a register for functions that don't need one) might have serious repercussions on the debugging of applications.

When the CFLAGS and CXXFLAGS variables are defined, combine the several optimization flags in one string. The default values contained in the stage3 archive that is unpacked should be good enough. The following one is just an example:

CODE Example CFLAGS and CXXFLAGS variables
# Compiler flags to set for all languages
COMMON_FLAGS=""
# Use the same settings for both variables
CFLAGS="${COMMON_FLAGS}"
CXXFLAGS="${COMMON_FLAGS}"
Tip
Although the GCC optimization article has more information on how the various compilation options can affect a system, the Safe CFLAGS article may be a more practical place for beginners to start optimizing their systems.

MAKEOPTS

The MAKEOPTS variable defines how many parallel compilations should occur when installing a package. A good choice is the number of CPUs (or CPU cores) in the system plus one, but this guideline isn't always perfect.

Warning
Using a large number of jobs can significantly impact memory consumption. A good recommendation is to have at least 2 GiB of RAM for every job specified (so, e.g. -j6 requires at least 12 GiB). To avoid running out of memory, lower the number of jobs to fit the available memory.
Tip
When using parallel emerges (--jobs), the effective number of jobs run can grow exponentially (up to make jobs multiplied by emerge jobs). This can be worked around by running a localhost-only distcc configuration that will limit the number of compiler instances per host.
CODE Example MAKEOPTS declaration in make.conf
MAKEOPTS="-j2"

TODO: set ACCEPT_KEYWORDS to unstable on bleeding edge arches

Ready, set, go!

Update the /mnt/gentoo/etc/portage/make.conf file to match personal preference and save (nano users would hit Ctrl+x).

Then continue with [[Handbook:Zulu Foxtrott/Installation/Base|Installing the Gentoo base system]].


{{Handbook:Parts/Navigator|Prev=Handbook:Zulu Foxtrott/Installation/Disks|Next=Handbook:Zulu Foxtrott/Installation/Base}}