User:SwifT/Complete Handbook/Versions media installation concerns

From Gentoo Wiki
Jump to:navigation Jump to:search

About the Gentoo releases

Gentoo versions

One of Gentoo's major advantages is that it does not really know versions. Once installed, the user has a Gentoo installation, not a Gentoo 2005.1 or 2004.3 installation. Therefore users will continue to benefit from the Gentoo development with every system update performed - there is no need to run through a specific upgrade procedure every time Gentoo makes a new release.

This is also reflected by the pace at which Gentoo provides new installation media: through an auto-build process, new media are provided on a weekly basis (for active architectures). These auto-builds contain all the necessary media to install Gentoo with, and is also the medium that we will use throughout this handbook.

Gentoo LiveDVD releases

Occasionally, Gentoo will create a Gentoo LiveDVD from which one can play with Gentoo before installing it. These releases are announced on the main Gentoo website.

Understand that the Gentoo installation procedure is a manual procedure, requiring lots of input from the administrator

The structure of a Gentoo Linux installation

Understand that the Gentoo installation procedure is quite different from most other Linux distributions: where other distributions try to perform most steps for the user, Gentoo Linux asks the user politely (but firmly) to do things actively.

Getting the hardware up and running, configuring the network, partitioning the disk(s), copying over the initial files, building additional software (including the kernel), ... all these steps should be performed before one can finally boot in a minimal Gentoo environment. Not that all these steps can't be automated (Gentoo even offers tools to automate a few of those steps and there might still be a few unofficial installers that automate most - if not all - steps) but by documenting these steps in great detail Gentoo almost forces the user to learn various Linux-related procedures.

The structure of a Gentoo installation is as follows:

  1. Download and boot a bootable system from which Gentoo can be installed
  2. Prepare the disk(s) and partitions to host Gentoo
  3. Download and extract the latest archive (stage file) which creates a minimal Gentoo environment to further install from
  4. Chroot into this minimal Gentoo environment and install a Linux kernel, core utilities and boot loader
  5. Reboot into the freshly installed Gentoo system

A huge advantage of letting the user perform all steps on their own is that the user can now decide how they want to install Gentoo - the options are there, the user needs to make a choice, over and over again. By clearly identifying the options and documenting the possible roads Gentoo hopes that the user is not scared but rather impressed.

Download, burn and boot

In order to boot a medium from which Gentoo can be installed, the first thing to know is for which architecture the installation should be done.

An architecture is a family of CPUs (processors) which support the same instructions. The two most prominent architectures in the desktop world are the x86 architecture and the x86_64 architecture (for which Gentoo uses the amd64 notation). But many other architectures exist, such as sparc, ppc (the PowerPC family), mips, arm, ...

Gentoo supports a number of architectures, namely:

Architecture Gentoo notation Information Example systems or CPUs
x86 x86 A 32-bit architecture used by CPUs that are often said to be "Intel compatible". It was, until recently, the most popular architecture for desktop PCs. Gentoo offers builds for i486 (supports all families) and i686 (supports Pentium and higher or compatible). i486, i686, Intel Core, AMD Athlon, Intel Atom
x86_64 amd64 A 64-bit architecture that is compatible with the x86 architecture. It was first used by AMD (under the AMD64 name) and Intel (under the EM64T name) and is now the most prominent architecture for medium and high-end desktop PCs. It is also commonly found in the server segment. AMD Athlon 64, AMD Opteron, AMD Sempron, AMD Phenom, Intel Pentium 4, Intel Core i3, Intel Core i5, Intel Core i7
IA64 ia64 A 64-bit architecture designed by Intel and used in their Intel Itanium processor series. This architecture is not compatible with x86 or x86_64 (aka amd64) and is mostly found in medium and high-end server series. Intel Itanium
Sparc sparc The SPARC architecture is best known by its most common producers, Sun (now Oracle) and Fujitsu. It is used in server systems although a few workstations exist as well. In Gentoo, only SPARC64 compatible CPUs are supported. E3000, Blade 1000, Ultra 2
PowerPC ppc A 32-bit architecture used by many Apple, IBM and Motorola processors. They are most commonly found in embedded systems. Apple OldWorld, Apple NewWorld, Genesi Pegasos, Efika, older IBM iSeries and pSeries
PowerPC 64 ppc64 The 64-bit variant of the PPC architecture, popular in both embedded as well as high-end performance servers. IBM RS/6000s, IBM pSeries, IBM iSeries
Alpha alpha The Alpha architecture is a 64-bit architecture developed by Digital Equipment Corporation (DEC). It is still in use by some mid-range and high-end servers, but the architecture is slowly being faded out. ES40, AlphaPC, UP1000, Noname
PA-RISC hppa Referred to as HPPA, the PA-RISC architecture is an instruction set developed by Hewlett-Packard and was used in their mid- and high-end server series until about 2008 (after which HP started using Intel Itanium) HP 9000, PA-8600
MIPS mips Developed by MIPS Technologies, the MIPS architecture entails multiple subfamilies (called revisions) such as MIPS I, MIPS III, MIPS32, MIPS64 and more. MIPS is most common in embedded systems. MIPS32 1074K, R16000
ARM arm This 32-bit architecture is a very popular architecture for embedded and small systems. Subarchitectures range from ARMv1 to ARMv7 (Cortex) and are often found in smartphones, tablets, handheld consoles, end-user GPS navigation systems, etc. StrongARM, Cortex-M

In this handbook, we focus on the architecture.

Download the media

The default installation media that Gentoo Linux uses are the minimal installation CDs, which host a bootable, very small Gentoo Linux environment with the right tools to install Gentoo Linux from. The CD images themselves can be downloaded from one of the many mirrors available.

On those mirrors, the minimal installation CDs can be found as follows:

  1. Go to the releases/ directory
  2. Select the right architecture, such as /
  3. Select the autobuilds/ directory
  4. Select the current-iso/ directory

Inside this location, the installation CD 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 CD. This file can be useful to verify if particular firmware or drivers are available on the installation CD 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 release engineering 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 DeepDigest application, although many others exist as well (see this Wikipedia article for details). 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 release engineering page:

user $gpg --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

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


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

If you wish to burn to USB there is also the ability to do that, there is an excellently written article explaining how to do so

Burning with Microsoft Windows

On Microsoft Windows, a number of tools exist that support burning ISOs on CDs.

  • With EasyCD Creator, select File, Record CD from CD image. Then change the Files of type to ISO image file. Then locate the ISO file and click Open. After clicking on Start recording the ISO image will be burned correctly onto the CD-R.
  • With Nero Burning ROM, cancel the wizard which automatically pops up and select Burn Image from the File menu. Select the image to burn and click Open. Now hit the Burn button and watch the brand new CD being burnt.

Burning with Linux

On Linux, the ISO file can be burned on a CD using the cdrecord command, part of the app-cdr/cdrtools package.

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

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

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

Booting the CD

With the CD burned, the installation of Gentoo Linux can now commence. Put the CD in the drive and reboot the system, making sure that the system now boots from the CD.

On most systems, it is possible to change the boot order at boot time once, such as by pressing F5, F8 or Esc (Escape) before the system starts booting the operating system. How to achieve this is specific to each system, so consult the system documentation of the computer if uncertain.

Once booted, the installation CD will greet the user with a root prompt, indicating that the system is waiting for further input:

root # 

This is the command-line prompt which will be used to install Gentoo Linux from in the next set of sections.