Difference between revisions of "Handbook:Parts/Installation/Base"

From Gentoo Wiki
Jump to:navigation Jump to:search
(Mention package name for future emerge reference. Link to the chroot section.)
(Add CPU_FLAGS_*)
Line 330: Line 330:
 
<!--T:133-->
 
<!--T:133-->
 
{{Warning|Although possible, setting <code>-*</code> (which will disable all USE values except the ones specified in {{Path|make.conf}}) is ''strongly'' discouraged and unwise. Ebuild developers choose certain default USE flag values in ebuilds in order to prevent conflicts, enhance security, and avoid errors, and other reasons. Disabling ''all'' USE flags will negate default behavior and may cause major issues.}}
 
{{Warning|Although possible, setting <code>-*</code> (which will disable all USE values except the ones specified in {{Path|make.conf}}) is ''strongly'' discouraged and unwise. Ebuild developers choose certain default USE flag values in ebuilds in order to prevent conflicts, enhance security, and avoid errors, and other reasons. Disabling ''all'' USE flags will negate default behavior and may cause major issues.}}
 +
 +
==== CPU_FLAGS_* ====
 +
 +
Some architectures (including AMD64/X86, ARM, PPC) have a [[USE_EXPAND]] variable called [[CPU_FLAGS_X86|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:
 +
{{Emerge|app-portage/cpuid2cpuflags}}
 +
 +
Inspect the output manually if curious:
 +
{{RootCmd|cpuid2cpuflags}}
 +
 +
Then copy the output into {{Path|package.use}}:
 +
{{RootCmd|echo "*/* $(cpuid2cpuflags)" > /etc/portage/package.use/00cpu-flags}}
  
 
=== Optional: Configuring the ACCEPT_LICENSE variable === <!--T:141-->
 
=== Optional: Configuring the ACCEPT_LICENSE variable === <!--T:141-->

Revision as of 02:01, 4 June 2022


Warning
Readers should not try to follow instructions directly from the Handbook:Parts namespace (which is THIS page!). The sections displayed below are used as a skeleton for transcluding information into the computer architecture specific handbooks and are therefore lacking critical information.

Please visit the Handbook list to read instructions for a relevant computer architecture.
Parts Handbook
Installation
About the installation
Choosing the media
Configuring the network
Preparing the disks
The stage file
Installing base system
Configuring the kernel
Configuring the system
Installing tools
Configuring the bootloader
Finalizing
Working with Gentoo
Portage introduction
USE flags
Portage features
Initscript system
Environment variables
Working with Portage
Files and directories
Variables
Mixing software branches
Additional tools
Custom package repository
Advanced features
OpenRC network configuration
Getting started
Advanced configuration
Modular networking
Wireless
Adding functionality
Dynamic management


Chrooting

Optional: Selecting mirrors

Distribution files

Tip
It is safe to skip this step when using non-Gentoo installation media. The app-portage/mirrorselect package can be emerged later within the stage3 (after Entering the new environment) and the actions defined in this section can be performed at that point.

In order to download source code quickly it is recommended to select a fast mirror. Portage will look in the make.conf file for the GENTOO_MIRRORS variable and use the mirrors listed therein. It is possible to surf to the Gentoo mirror list and search for a mirror (or mirrors) that is close to the system's physical location (as those are most frequently the fastest ones). However, we provide a nice tool called mirrorselect which provides users with a nice interface to select the mirrors needed. Just navigate to the mirrors of choice and press Spacebar to select one or more mirrors.

root #mirrorselect -i -o >> /mnt/gentoo/etc/portage/make.conf

Gentoo ebuild repository

A second important step in selecting mirrors is to configure the Gentoo ebuild repository via the /etc/portage/repos.conf/gentoo.conf file. This file contains the sync information needed to update the package repository (the collection of ebuilds and related files containing all the information Portage needs to download and install software packages).

Configuring the repository can be done in a few simple steps. First, if it does not exist, create the repos.conf directory:

root #mkdir --parents /mnt/gentoo/etc/portage/repos.conf

Next, copy the Gentoo repository configuration file provided by Portage to the (newly created) repos.conf directory:

root #cp /mnt/gentoo/usr/share/portage/config/repos.conf /mnt/gentoo/etc/portage/repos.conf/gentoo.conf

Take a peek with a text editor or by using the cat command. The inside of the file should be in .ini format and look like this:

FILE /mnt/gentoo/etc/portage/repos.conf/gentoo.conf
[DEFAULT]
main-repo = gentoo
 
[gentoo]
location = /var/db/repos/gentoo
sync-type = rsync
sync-uri = rsync://rsync.gentoo.org/gentoo-portage
auto-sync = yes
sync-rsync-verify-jobs = 1
sync-rsync-verify-metamanifest = yes
sync-rsync-verify-max-age = 24
sync-openpgp-key-path = /usr/share/openpgp-keys/gentoo-release.asc
sync-openpgp-key-refresh-retry-count = 40
sync-openpgp-key-refresh-retry-overall-timeout = 1200
sync-openpgp-key-refresh-retry-delay-exp-base = 2
sync-openpgp-key-refresh-retry-delay-max = 60
sync-openpgp-key-refresh-retry-delay-mult = 4

The default sync-uri variable value listed above will determine a mirror location based on a rotation. This will aid in easing bandwidth stress on Gentoo's infrastructure and will provide a fail-safe in case a specific mirror is offline. It is recommended the default URI is retained unless a local, private Portage mirror will be used.

Tip
For those interested, the official specification for Portage's plug-in sync API can be found in the Portage project's Sync article.

Copy DNS info

One thing still remains to be done before entering the new environment and that is copying over the DNS information in /etc/resolv.conf. This needs to be done to ensure that networking still works even after entering the new environment. /etc/resolv.conf contains the name servers for the network.

To copy this information, it is recommended to pass the --dereference option to the cp command. This ensures that, if /etc/resolv.conf is a symbolic link, that the link's target file is copied instead of the symbolic link itself. Otherwise in the new environment the symbolic link would point to a non-existing file (as the link's target is most likely not available inside the new environment).

root #cp --dereference /etc/resolv.conf /mnt/gentoo/etc/

Mounting the necessary filesystems

In a few moments, the Linux root will be changed towards the new location. To make sure that the new environment works properly, certain filesystems need to be made available there as well.

The filesystems that need to be made available are:

  • /proc/ which is a pseudo-filesystem (it looks like regular files, but is actually generated on-the-fly) from which the Linux kernel exposes information to the environment
  • /sys/ which is a pseudo-filesystem, like /proc/ which it was once meant to replace, and is more structured than /proc/
  • /dev/ is a regular file system, partially managed by the Linux device manager (usually udev), which contains all device files
  • /run/ is a temporary file system used for files generated at runtime, such as PID files or locks

The /proc/ location will be mounted on /mnt/gentoo/proc/ whereas the others are bind-mounted. The latter means that, for instance, /mnt/gentoo/sys/ will actually be /sys/ (it is just a second entry point to the same filesystem) whereas /mnt/gentoo/proc/ is a new mount (instance so to speak) of the filesystem.

root #mount --types proc /proc /mnt/gentoo/proc
root #mount --rbind /sys /mnt/gentoo/sys
root #mount --make-rslave /mnt/gentoo/sys
root #mount --rbind /dev /mnt/gentoo/dev
root #mount --make-rslave /mnt/gentoo/dev
root #mount --bind /run /mnt/gentoo/run
root #mount --make-slave /mnt/gentoo/run
Note
The --make-rslave operations are needed for systemd support later in the installation.
Warning
When using non-Gentoo installation media, this might not be sufficient. Some distributions make /dev/shm a symbolic link to /run/shm/ which, after the chroot, becomes invalid. Making /dev/shm/ a proper tmpfs mount up front can fix this:
root #test -L /dev/shm && rm /dev/shm && mkdir /dev/shm
root #mount --types tmpfs --options nosuid,nodev,noexec shm /dev/shm

Also ensure that mode 1777 is set:

root #chmod 1777 /dev/shm /run/shm

Entering the new environment

Now that all partitions are initialized and the base environment installed, it is time to enter the new installation environment by chrooting into it. This means that the session will change its root (most top-level location that can be accessed) from the current installation environment (installation CD or other installation medium) to the installation system (namely the initialized partitions). Hence the name, change root or chroot.

This chrooting is done in three steps:

  1. The root location is changed from / (on the installation medium) to /mnt/gentoo/ (on the partitions) using chroot
  2. Some settings (those in /etc/profile) are reloaded in memory using the source command
  3. The primary prompt is changed to help us remember that this session is inside a chroot environment.
root #chroot /mnt/gentoo /bin/bash
root #source /etc/profile
root #export PS1="(chroot) ${PS1}"

From this point, all actions performed are immediately on the new Gentoo Linux environment. Of course it is far from finished, which is why the installation still has some sections left!

Tip
If the Gentoo installation is interrupted anywhere after this point, it should be possible to 'resume' the installation at this step. There is no need to repartition the disks again! Simply mount the root partition and run the steps above starting with copying the DNS info to re-enter the working environment. This is also useful for fixing bootloader issues. More information can be found in the chroot article.

Mounting the boot partition

Now that the new environment has been entered, it is necessary to mount the boot partition. This will be important when it is time to compile the kernel and install the bootloader:

root #mount /dev/sda1 /boot

Configuring Portage

Installing a Gentoo ebuild repository snapshot from the web

Next step is to install a snapshot of the Gentoo ebuild repository. This snapshot contains a collection of files that informs Portage about available software titles (for installation), which profiles the system administrator can select, package or profile specific news items, etc.

The use of emerge-webrsync is recommended for those who are behind restrictive firewalls (it uses HTTP/FTP protocols for downloading the snapshot) and saves network bandwidth. Readers who have no network or bandwidth restrictions can happily skip down to the next section.

This will fetch the latest snapshot (which is released on a daily basis) from one of Gentoo's mirrors and install it onto the system:

root #emerge-webrsync
Note
During this operation, emerge-webrsync might complain about a missing /var/db/repos/gentoo/ location. This is to be expected and nothing to worry about - the tool will create the location.

From this point onward, Portage might mention that certain updates are recommended to be executed. This is because system packages installed through the stage file might have newer versions available; Portage is now aware of new packages because of the repository snapshot. Package updates can be safely ignored for now; updates can be delayed until after the Gentoo installation has finished.

Optional: Updating the Gentoo ebuild repository

It is possible to update the Gentoo ebuild repository to the latest version. The previous emerge-webrsync command will have installed a very recent snapshot (usually recent up to 24h) so this step is definitely optional.

Suppose there is a need for the last package updates (up to 1 hour), then use emerge --sync. This command will use the rsync protocol to update the Gentoo ebuild repository (which was fetched earlier on through emerge-webrsync) to the latest state.

root #emerge --sync

On slow terminals, like some framebuffers or serial consoles, it is recommended to use the --quiet option to speed up the process:

root #emerge --sync --quiet

Reading news items

When the Gentoo ebuild repository is synchronized, Portage may output informational messages similar to the following:

* IMPORTANT: 2 news items need reading for repository 'gentoo'.
* Use eselect news to read news items.

News items were created to provide a communication medium to push critical messages to users via the Gentoo ebuild repository. To manage them, use eselect news. The eselect application is a Gentoo-specific utility that allows for a common management interface for system administration. In this case, eselect is asked to use its news module.

For the news module, three operations are most used:

  • With list an overview of the available news items is displayed.
  • With read the news items can be read.
  • With purge news items can be removed once they have been read and will not be reread anymore.
root #eselect news list
root #eselect news read

More information about the news reader is available through its manual page:

root #man news.eselect

Choosing the right profile

A profile is a building block for any Gentoo system. Not only does it specify default values for USE, CFLAGS, and other important variables, it also locks the system to a certain range of package versions. These settings are all maintained by Gentoo's Portage developers.

To see what profile the system is currently using, run eselect using the profile module:

root #eselect profile list
Available profile symlink targets:
  [1]   default/linux/amd64/17.1 *
  [2]   default/linux/amd64/17.1/desktop
  [3]   default/linux/amd64/17.1/desktop/gnome
  [4]   default/linux/amd64/17.1/desktop/kde
Note
The output of the command is just an example and evolves over time.
Note
When using systemd, please make sure the profile name contains systemd. Otherwise, please make sure the profile name does not contain systemd.

As can be seen, there are also desktop subprofiles available for some architectures.

Warning
Profile upgrades are not to be taken lightly. When selecting the initial profile, make sure to use profile corresponding to the same version as the one initially used by stage3 (e.g. 17.1). Each new profile version is announced through a news item containing migration instructions. Make sure to read it and follow them before switching to a newer profile.

After viewing the available profiles for the amd64 architecture, users can select a different profile for the system:

root #eselect profile set 2
Note
This is a placeholder for architecture-specific profile information
Note
The developer subprofile is specifically for Gentoo Linux development and is not meant to be used by casual users.

Updating the @world set

At this point, it is wise to update the system's @world set so that a base can be established.

This following step is necessary so the system can apply any updates or USE flag changes which have appeared since the stage3 was built and from any profile selection:

root #emerge --ask --verbose --update --deep --newuse @world
Tip
If a full scale desktop environment profile has been selected this process could greatly extend the amount of time necessary for the install process. Those in a time crunch can work by this 'rule of thumb': the shorter the profile name, the less specific the system's @world set; the less specific the @world set, the fewer packages the system will require. In other words:
  • Selecting default/linux/amd64/17.1 will require very few packages to be updated, whereas
  • Selecting default/linux/amd64/17.1/desktop/gnome/systemd will require many packages to be installed since the init system is changing from OpenRC to systemd, and the GNOME desktop environment framework will be installed.

Configuring the USE variable

USE is one of the most powerful variables Gentoo provides to its users. Several programs can be compiled with or without optional support for certain items. For instance, some programs can be compiled with support for GTK+ or with support for Qt. Others can be compiled with or without SSL support. Some programs can even be compiled with framebuffer support (svgalib) instead of X11 support (X-server).

Most distributions compile their packages with support for as much as possible, increasing the size of the programs and startup time, not to mention an enormous amount of dependencies. With Gentoo users can define what options a package should be compiled with. This is where USE comes into play.

In the USE variable users define keywords which are mapped onto compile-options. For instance, ssl will compile SSL support in the programs that support it. -X will remove X-server support (note the minus sign in front). gnome gtk -kde -qt5 will compile programs with GNOME (and GTK+) support, and not with KDE (and Qt) support, making the system fully tweaked for GNOME (if the architecture supports it).

The default USE settings are placed in the make.defaults files of the Gentoo profile used by the system. Gentoo uses a (complex) inheritance system for its profiles, which we will not dive into at this stage. The easiest way to check the currently active USE settings is to run emerge --info and select the line that starts with USE:

root #emerge --info | grep ^USE
USE="X acl alsa amd64 berkdb bindist bzip2 cli cracklib crypt cxx dri ..."
Note
The above example is truncated, the actual list of USE values is much, much larger.

A full description on the available USE flags can be found on the system in /var/db/repos/gentoo/profiles/use.desc.

root #less /var/db/repos/gentoo/profiles/use.desc

Inside the less command, scrolling can be done using the and keys, and exited by pressing q.

As an example we show a USE setting for a KDE-based system with DVD, ALSA, and CD recording support:

root #nano -w /etc/portage/make.conf
FILE /etc/portage/make.confEnabling flags for a KDE/Plasma-based system with DVD, ALSA, and CD recording support
USE="-gtk -gnome qt5 kde dvd alsa cdr"

When a USE value is defined in /etc/portage/make.conf it is added to the system's USE flag list. USE flags can be globally removed by adding a - minus sign in front of the value in the the list. For example, to disable support for X graphical environments, -X can be set:

FILE /etc/portage/make.confIgnoring default USE flags
USE="-X acl alsa"
Warning
Although possible, setting -* (which will disable all USE values except the ones specified in make.conf) is strongly discouraged and unwise. Ebuild developers choose certain default USE flag values in ebuilds in order to prevent conflicts, enhance security, and avoid errors, and other reasons. Disabling all USE flags will negate default behavior and may cause major issues.

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:

root #emerge --ask app-portage/cpuid2cpuflags

Inspect the output manually if curious:

root #cpuid2cpuflags

Then copy the output into package.use:

root #echo "*/* $(cpuid2cpuflags)" > /etc/portage/package.use/00cpu-flags

Optional: Configuring the ACCEPT_LICENSE variable

All of the Gentoo packages are tagged with the license(s) the package falls under. This allows users to select software by specific licenses or groups of licenses prior to installing it.

Important
The LICENSE variable in an ebuild is only a guideline for Gentoo developers and users. It is not a legal statement, and there is no guarantee that it will reflect reality. So don't rely on it, but check the package itself in depth, including all files that you use.

Portage uses the ACCEPT_LICENSE variable to determine which packages to allow without prompting the user for the licenses previously accepted. Exceptions can be made per-package in /etc/portage/package.license as well.

The license groups defined in the Gentoo repository, managed by the Gentoo Licenses project, are:

Group Name Description
@GPL-COMPATIBLE GPL compatible licenses approved by the Free Software Foundation [a_license 1]
@FSF-APPROVED Free software licenses approved by the FSF (includes @GPL-COMPATIBLE)
@OSI-APPROVED Licenses approved by the Open Source Initiative [a_license 2]
@MISC-FREE Misc licenses that are probably free software, i.e. follow the Free Software Definition [a_license 3] but are not approved by either FSF or OSI
@FREE-SOFTWARE Combines @FSF-APPROVED, @OSI-APPROVED and @MISC-FREE
@FSF-APPROVED-OTHER FSF-approved licenses for "free documentation" and "works of practical use besides software and documentation" (including fonts)
@MISC-FREE-DOCS Misc licenses for free documents and other works (including fonts) that follow the free definition [a_license 4] but are NOT listed in @FSF-APPROVED-OTHER
@FREE-DOCUMENTS Combines @FSF-APPROVED-OTHER and @MISC-FREE-DOCS
@FREE Metaset of all licenses with the freedom to use, share, modify and share modifications. Combines @FREE-SOFTWARE and @FREE-DOCUMENTS
@BINARY-REDISTRIBUTABLE Licenses that at least permit free redistribution of the software in binary form. Includes @FREE
@EULA License agreements that try to take away your rights. These are more restrictive than "all-rights-reserved" or require explicit approval

Gentoo comes with a predefined value in the profiles, for example:

user $portageq envvar ACCEPT_LICENSE
@FREE

This can be customized system wide by changing /etc/portage/make.conf. The default value will only accept licenses that are explicitly approved by the Free Software Foundation, the Open Source Initiative, or that follow the Free Software Definition:

FILE /etc/portage/make.confCustomizing ACCEPT_LICENSE
ACCEPT_LICENSE="-* @FREE"

Per package overrides can then be added if necessary and desired, for example:

FILE /etc/portage/package.license/kernelSample license acceptance
app-arch/unrar unRAR
sys-kernel/linux-firmware @BINARY-REDISTRIBUTABLE
sys-firmware/intel-microcode intel-ucode

Optional: Using systemd as the system and service manager

The remainder of the Gentoo handbook will provide systemd steps alongside OpenRC (the traditional Gentoo init system) where separate steps or recommendations are necessary. System administrators should also consult the systemd article for more details on managing systemd as the system and service manager.

Timezone

Select the timezone for the system. Look for the available timezones in /usr/share/zoneinfo/:

root #ls /usr/share/zoneinfo

Suppose the timezone of choice is Europe/Brussels.

OpenRC

We write the timezone name into the /etc/timezone file.

root #echo "Europe/Brussels" > /etc/timezone

Please avoid the /usr/share/zoneinfo/Etc/GMT* timezones as their names do not indicate the expected zones. For instance, GMT-8 is in fact GMT+8.

Next, reconfigure the sys-libs/timezone-data package, which will update the /etc/localtime file for us, based on the /etc/timezone entry. The /etc/localtime file is used by the system C library to know the timezone the system is in.

root #emerge --config sys-libs/timezone-data

systemd

A slightly different approach is employed when using systemd. A symbolic link is generated:

root #ln -sf ../usr/share/zoneinfo/Europe/Brussels /etc/localtime

Later, when systemd is running, the timezone and related settings can be configured with the timedatectl command.

Configure locales

Note
This step does not apply to users of the musl libc. Users who do not know what that means should perform this step.

Locale generation

Most users will want to use only one or two locales on their system.

Locales specify not only the language that the user should use to interact with the system, but also the rules for sorting strings, displaying dates and times, etc. Locales are case sensitive and must be represented exactly as described. A full listing of available locales can be found in the /usr/share/i18n/SUPPORTED file.

Supported system locales must be defined in the /etc/locale.gen file.

root #nano -w /etc/locale.gen

The following locales are an example to get both English (United States) and German (Germany/Deutchland) with the accompanying character formats (like UTF-8).

FILE /etc/locale.genEnabling US and DE locales with the appropriate character formats
en_US ISO-8859-1
en_US.UTF-8 UTF-8
de_DE ISO-8859-1
de_DE.UTF-8 UTF-8
Warning
We strongly suggest adding at least one UTF-8 locale because many applications may require it to build properly.

The next step is to run the locale-gen command. This command generates all locales specified in the /etc/locale.gen file.

root #locale-gen

To verify that the selected locales are now available, run locale -a.

Locale selection

Once done, it is now time to set the system-wide locale settings. Again we use eselect for this, now with the locale module.

With eselect locale list, the available targets are displayed:

root #eselect locale list
Available targets for the LANG variable:
  [1]  C
  [2]  C.utf8
  [3]  en_US
  [4]  en_US.iso88591
  [5]  en_US.utf8
  [6]  de_DE
  [7]  de_DE.iso88591
  [8]  de_DE.iso885915
  [9]  de_DE.utf8
  [10] POSIX
  [ ]  (free form)

With eselect locale set <NUMBER> the correct locale can be selected:

root #eselect locale set 9

Manually, this can still be accomplished through the /etc/env.d/02locale file and for Systemd the /etc/locale.conf file:

FILE /etc/env.d/02localeManually setting system locale definitions
LANG="de_DE.UTF-8"
LC_COLLATE="C.UTF-8"

Setting the locale will avoid warnings and errors during kernel and software compilations later in the installation.

Now reload the environment:

root #env-update && source /etc/profile && export PS1="(chroot) ${PS1}"

A full Localization guide to provide additional guidance through the locale selection process. Another interesting article is the UTF-8 guide for very specific information to enable UTF-8 on the system.