Choosing the right installation medium
Hardware requirements
Before proceeding with the installation process, minimum hardware requirements should be met in order to successfully install Gentoo for the amd64 system architecture.
| Minimal CD | LiveDVD | |
|---|---|---|
| CPU | Any x86-64 CPU, both AMD64 and Intel 64 | |
| Memory | 2 GB | |
| Disk space | 8 GB (excluding swap space) | |
| Swap space | At least 2 GB | |
The AMD64 project is a good place to be for more information about Gentoo's amd64 support.
Media instalacyjne Gentoo Linux
While it's recommended to use the official Gentoo boot media when installing, it's possible to use other installation environments. However, there is no guarantee they will contain required components. If an alternate install environment is used, skip to Preparing the disks.
Minimal installation CD
The Gentoo minimal installation CD is a small, bootable image: a self-contained Gentoo environment. This image is maintained by Gentoo developers and designed to allow any user with an Internet connection to install Gentoo. During the boot process, the hardware is detected, and appropriate drivers are automatically loaded.
Minimal Installation CD releases are named using the format: install-<arch>-minimal-<release timestamp>.iso.
The Gentoo LiveGUI
Some users may find it easier to install Gentoo using the LiveGUI, which provides a KDE desktop environment. In addition to providing a useful graphical environment, the LiveGUI has more kernel modules and firmware, which can help with using modern Wi-Fi chipsets.
The Gentoo LiveGUI USB image is built for amd64 and arm64 platforms weekly.
What are stage files?
A stage file is an archive which serves as the seed for a Gentoo environment.
Stage 3 files can be downloaded from releases/amd64/autobuilds/ on any of the official Gentoo mirrors. Stages are updated frequently and are therefore not included within official live images.
For now, stage files can be ignored. They will be described in greater detail later when they are needed
Historically, the handbook described installation steps for stage files with versions lower than 3. These stages contained environments unsuitable for typical installations, and are no longer covered in the handbook.
Downloading
Obtain the media
The default installation media used by Gentoo Linux are the minimal installation CDs, which provide a very small, bootable, Gentoo Linux environment. This environment contains the necessary tools to install Gentoo. The 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 by:
- Connect to the mirror, typically using a local one found at Gentoo source mirrors.
- Navigate to the releases/ directory.
- Select the directory for the relevant target architecture (such as amd64/).
- Select the autobuilds/ directory.
- 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:
[TXT] install-amd64-minimal-20231112T170154Z.iso.asc 2023-11-12 20:41 488
[TXT] install-amd64-minimal-20231119T164701Z.iso.asc 2023-11-19 18:41 488
[TXT] install-amd64-minimal-20231126T163200Z.iso.asc 2023-11-26 18:41 488
[TXT] install-amd64-minimal-20231203T170204Z.iso.asc 2023-12-03 18:41 488
[TXT] install-amd64-minimal-20231210T170356Z.iso.asc 2023-12-10 19:01 488
[TXT] install-amd64-minimal-20231217T170203Z.iso.asc 2023-12-17 20:01 488
[TXT] install-amd64-minimal-20231224T164659Z.iso.asc 2023-12-24 20:41 488
[TXT] install-amd64-minimal-20231231T163203Z.iso.asc 2023-12-31 19:01 488
[ ] install-amd64-minimal-20240107T170309Z.iso 2024-01-07 20:42 466M
[ ] install-amd64-minimal-20240107T170309Z.iso.CONTENTS.gz 2024-01-07 20:42 9.8K
[ ] install-amd64-minimal-20240107T170309Z.iso.DIGESTS 2024-01-07 21:01 1.3K
[TXT] install-amd64-minimal-20240107T170309Z.iso.asc 2024-01-07 21:01 488
[ ] install-amd64-minimal-20240107T170309Z.iso.sha256 2024-01-07 21:01 660
[TXT] latest-install-amd64-minimal.txt 2024-01-08 02:01 653
In the above example, the install-amd64-minimal-20240107T170309Z.iso file is the minimal installation CD itself. But as can be seen, other related files exist as well:
- A .CONTENTS.gz file which is a gz-compressed 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 ISO file integrity.
- A .asc file which is a cryptographic signature of the ISO file. This can be used to verify image integrity and authenticity - that the download is indeed provided by the Gentoo Release Engineering team, free from tampering.
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 .iso.asc file for the .iso file as well.
The .DIGESTS file is only needed if the signature in the .iso.asc file is not verified.
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.
The .asc file provides a cryptographic signature of the ISO. By validating it, one can make sure that the installation file is provided by the Gentoo Release Engineering team and is intact and unmodified.
Microsoft Windows-based verification
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 in the .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 command can be used to verify the cryptographic signature in the .asc file.
When importing Gentoo keys, verify that the fingerprint (
BB572E0E2D182910) matches.Gentoo keys can be downloaded from hkps://keys.gentoo.org using fingerprints available on the signatures page:
user $gpg --keyserver hkps://keys.gentoo.org --recv-keys 13EBBDBEDE7A12775DFDB1BABB572E0E2D182910gpg: directory '/root/.gnupg' created gpg: keybox '/root/.gnupg/pubring.kbx' created gpg: /root/.gnupg/trustdb.gpg: trustdb created gpg: key BB572E0E2D182910: public key "Gentoo Linux Release Engineering (Automated Weekly Release Key) <releng@gentoo.org>" imported gpg: Total number processed: 1 gpg: imported: 1
Alternatively you can use instead the WKD to download the key:
user $gpg --auto-key-locate=clear,nodefault,wkd --locate-key releng@gentoo.orggpg: key 9E6438C817072058: public key "Gentoo Linux Release Engineering (Gentoo Linux Release Signing Key) <releng@gentoo.org>" imported
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
pub dsa1024 2004-07-20 [SC] [expires: 2025-07-01]
D99EAC7379A850BCE47DA5F29E6438C817072058
uid [ unknown] Gentoo Linux Release Engineering (Gentoo Linux Release Signing Key) <releng@gentoo.org>
sub elg2048 2004-07-20 [E] [expires: 2025-07-01]
Or if using official Gentoo release media, import the key from /usr/share/openpgp-keys/gentoo-release.asc (provided by sec-keys/openpgp-keys-gentoo-release):
user $gpg --import /usr/share/openpgp-keys/gentoo-release.ascgpg: directory '/home/larry/.gnupg' created gpg: keybox '/home/larry/.gnupg/pubring.kbx' created gpg: key DB6B8C1F96D8BF6D: 2 signatures not checked due to missing keys gpg: /home/larry/.gnupg/trustdb.gpg: trustdb created gpg: key DB6B8C1F96D8BF6D: public key "Gentoo ebuild repository signing key (Automated Signing Key) <infrastructure@gentoo.org>" imported gpg: key 9E6438C817072058: 3 signatures not checked due to missing keys gpg: key 9E6438C817072058: public key "Gentoo Linux Release Engineering (Gentoo Linux Release Signing Key) <releng@gentoo.org>" imported gpg: key BB572E0E2D182910: 1 signature not checked due to a missing key gpg: key BB572E0E2D182910: public key "Gentoo Linux Release Engineering (Automated Weekly Release Key) <releng@gentoo.org>" imported gpg: key A13D0EF1914E7A72: 1 signature not checked due to a missing key gpg: key A13D0EF1914E7A72: public key "Gentoo repository mirrors (automated git signing key) <repomirrorci@gentoo.org>" imported gpg: Total number processed: 4 gpg: imported: 4 gpg: no ultimately trusted keys found
Next verify the cryptographic signature:
user $gpg --verify install-amd64-minimal-20240107T170309Z.iso.ascgpg: assuming signed data in 'install-amd64-minimal-20240107T170309Z.iso'
gpg: Signature made Sun 07 Jan 2024 03:01:10 PM CST
gpg: using RSA key 534E4209AB49EEE1C19D96162C44695DB9F6043D
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
Subkey fingerprint: 534E 4209 AB49 EEE1 C19D 9616 2C44 695D B9F6 043D
To be absolutely certain that everything is valid, verify the fingerprint shown with the fingerprint on the Gentoo signatures page.
It's generally good practice to mark an imported key as trusted, once it's certain the key is trustworthy. When trusted keys are verified, gpg will not say unknown and warn about the signature being untrusted.
Writing the boot media
Of course, with just an ISO file downloaded, the Gentoo Linux installation cannot be started. The ISO file must be written to bootable media. This generally requires that the image is extracted to a filesystem, or written directly to a device.
Writing a bootable USB
Most modern systems support booting from a USB device.
Writing with Linux
dd is typically available on most Linux distros, and can be used to write the Gentoo boot media to a USB drive.
Determining the USB device path
Before writing, the path to the desired storage device must be determined.
dmesg will display detailed information describing the storage device as it is added to the system:
root #dmesg[268385.319745] sd 19:0:0:0: [sdd] 60628992 512-byte logical blocks: (31.0 GB/28.9 GiB)
Alternatively, lsblk can be used to display available storage devices:
root #lsblksdd 8:48 1 28.9G 0 disk ├─sdd1 8:49 1 246K 0 part ├─sdd2 8:50 1 2.8M 0 part ├─sdd3 8:51 1 463.5M 0 part └─sdd4 8:52 1 300K 0 part
Once the device name has been determined, this can be added to the path prefix /dev/ to get the device path /dev/sdd.
Using the base device path, ie. sdd opposed to sdd1, is recommend as the Gentoo boot media contains a full GPT partition scheme.
Writing with dd
Be sure to check the target (of=target) path before executing dd, as it will be overwritten.
With the device path (/dev/sdd) and boot media install-amd64-minimal-<release timestamp>.iso ready:
root #dd if=install-amd64-minimal-<release timestamp>.iso of=/dev/sdd bs=4096 status=progress && syncif= specifies the input file, of= specifies the output file, which in this case, is a device.
bs=4096 is used as it speeds up transfers in most cases, status=progress displays transfers stats.
Burning a disk
A more elaborate set of instructions can be found in CD/DVD/BD_writing#Image_writing.
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-amd64-minimal-20141204.isoUsers 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.
Booting
Booting the installation media
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 newly attached bootable media.
When installing Gentoo on a system with an UEFI firmware interface, ensure the live image has been booted in UEFI mode. In the accidental event that DOS/legacy BIOS boot was initiated, then it will be necessary to reboot in UEFI mode before finalizing the Gentoo Linux installation.
Ensure that the installation media is inserted or plugged into the system, and reboot. A GRUB boot prompt should be shown with various boot entries. At this screen, Enter will begin the boot process with the default boot options. To boot the installation media with customized boot options, such as passing additional kernel parameters or the following hardware options, highlight a boot entry, then press the e key to edit the boot entry. Make the necessary modification(s), then press ctrl+x or F10 to boot the modified entry.
In all likelihood, the default gentoo kernel, as mentioned above, without specifying any of the optional parameters will work just fine. For boot troubleshooting and expert options, continue on with this section. Otherwise, just press Enter and skip ahead to Extra hardware configuration.
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 entries 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:
Kernel choices
- gentoo
- Default kernel with support for K8 CPUs (including NUMA support) and EM64T CPUs.
- gentoo-nofb
- Same as gentoo but without framebuffer support.
- memtest86
- Test the system RAM for errors.
Alongside the kernel, boot options help in tuning the boot process further.
Hardware options
- acpi=on
- This loads support for ACPI and also causes the acpid daemon to be started by the CD on boot. This is only needed if the system requires ACPI to function properly. This is not required for Hyperthreading support.
- acpi=off
- Completely disables ACPI. This is useful on some older systems and is also a requirement for using APM. This will disable any Hyperthreading support of your processor.
- console=X
- This sets up serial console access for the CD. The first option is the device, usually ttyS0, followed by any connection options, which are comma separated. The default options are 9600,8,n,1.
- dmraid=X
- This allows for passing options to the device-mapper RAID subsystem. Options should be encapsulated in quotes.
- doapm
- This loads APM driver support. This also requires that
acpi=off. - dopcmcia
- This loads support for PCMCIA and Cardbus hardware and also causes the pcmcia cardmgr to be started by the CD on boot. This is only required when booting from PCMCIA/Cardbus devices.
- doscsi
- This loads support for most SCSI controllers. This is also a requirement for booting most USB devices, as they use the SCSI subsystem of the kernel.
- sda=stroke
- This allows the user to partition the whole hard disk even when the BIOS is unable to handle large disks. This option is only used on machines with an older BIOS. Replace sda with the device that requires this option.
- ide=nodma
- This forces the disabling of DMA in the kernel and is required by some IDE chipsets and also by some CDROM drives. If the system is having trouble reading from the IDE CDROM, try this option. This also disables the default hdparm settings from being executed.
- noapic
- This disables the Advanced Programmable Interrupt Controller that is present on newer motherboards. It has been known to cause some problems on older hardware.
- nodetect
- This disables all of the autodetection done by the CD, including device autodetection and DHCP probing. This is useful for debugging a failing CD or driver.
- nodhcp
- This disables DHCP probing on detected network cards. This is useful on networks with only static addresses.
- nodmraid
- Disables support for device-mapper RAID, such as that used for on-board IDE/SATA RAID controllers.
- nofirewire
- This disables the loading of Firewire modules. This should only be necessary if your Firewire hardware is causing a problem with booting the CD.
- nogpm
- This disables gpm console mouse support.
- nohotplug
- This disables the loading of the hotplug and coldplug init scripts at boot. This is useful for debugging a failing CD or driver.
- nokeymap
- This disables the keymap selection used to select non-US keyboard layouts.
- nolapic
- This disables the local APIC on Uniprocessor kernels.
- nosata
- This disables the loading of Serial ATA modules. This is used if the system is having problems with the SATA subsystem.
- nosmp
- This disables SMP, or Symmetric Multiprocessing, on SMP-enabled kernels. This is useful for debugging SMP-related issues with certain drivers and motherboards.
- nosound
- This disables sound support and volume setting. This is useful for systems where sound support causes problems.
- nousb
- This disables the autoloading of USB modules. This is useful for debugging USB issues.
- slowusb
- This adds some extra pauses into the boot process for slow USB CDROMs, like in the IBM BladeCenter.
Logical volume/device management
- dolvm
- This enables support for Linux's Logical Volume Management.
Other options
- debug
- Enables debugging code. This might get messy, as it displays a lot of data to the screen.
- docache
- This caches the entire runtime portion of the CD into RAM, which allows the user to umount /mnt/cdrom and mount another CDROM. This option requires that there is at least twice as much available RAM as the size of the CD.
- doload=X
- This causes the initial ramdisk to load any module listed, as well as dependencies. Replace X with the module name. Multiple modules can be specified by a comma-separated list.
- dosshd
- Starts sshd on boot, which is useful for unattended installs.
- passwd=foo
- Sets whatever follows the equals as the root password, which is required for dosshd since the root password is by default scrambled.
- noload=X
- This causes the initial ramdisk to skip the loading of a specific module that may be causing a problem. Syntax matches that of doload.
- nonfs
- Disables the starting of portmap/nfsmount on boot.
- nox
- This causes an X-enabled LiveCD to not automatically start X, but rather, to drop to the command line instead.
- scandelay
- This causes the CD to pause for 10 seconds during certain portions the boot process to allow for devices that are slow to initialize to be ready for use.
- scandelay=X
- This allows the user to specify a given delay, in seconds, to be added to certain portions of the boot process to allow for devices that are slow to initialize to be ready for use. Replace X with the number of seconds to pause.
The bootable media will check for
no* options before do* options, so that options can be overridden in the exact order specified.Now boot the media, select a kernel (if the default gentoo kernel does not suffice) and boot options. As an example, we boot the gentoo kernel, with dopcmcia as a kernel parameter:
boot:gentoo dopcmciaNext the user will be greeted with a boot screen and progress bar. If the installation is done on a system with a non-US keyboard, make sure to immediately press Alt+F1 to switch to verbose mode and follow the prompt. If no selection is made in 10 seconds the default (US keyboard) will be accepted and the boot process will continue. Once the boot process completes, the user is automatically logged in to the "Live" Gentoo Linux environment as the root user, the super user. A root prompt is displayed on the current console, and one can switch to other consoles by pressing Alt+F2, Alt+F3 and Alt+F4. Get back to the one started on by pressing Alt+F1.
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 8139tooOptional: 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 #passwdNew 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 johnNew 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 - johnOptional: Viewing documentation while installing
TTYs
To view the Gentoo handbook from a TTY during the installation, first create a user account as described above, then press Alt+F2 to go to a new terminal (TTY) and login as the newly created user. Following the principle of least privilege, it is best practice to avoid browsing the web or generally performing any task with higher privileges than necessary. The root account has full control of the system and therefore must be used sparingly.
During the installation, the links web browser can be used to browse the Gentoo handbook - of course only from the moment that the Internet connection is working.
user $links https://wiki.gentoo.org/wiki/Handbook:AMD64To go back to the original terminal, press Alt+F1.
When booted to the Gentoo minimal or Gentoo admin environments, seven TTYs will be available. They can be switched by pressing Alt then a function key between F1-F7. It can be useful to switch to a new terminal when waiting for job to complete, to open documentation, etc.
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 provide/receive 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 startIf 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.