Handbook:PPC/Installation/Media

From Gentoo Wiki
Jump to:navigation Jump to:search
PPC 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


Hardware requirements

Before proceeding with the installation process, minimum hardware requirements should be met in order to successfully install Gentoo for the ppc system architecture.


System overview
Apple NewWorld Machines Power/PowerPC microprocessors (G3, G4, G5) such as iMac, eMac, iBook PowerBook, Xserver, PowerMac
Apple OldWorld machines Apple Machines with an Open Firmware revision less than 3, such as the Beige G3s, PCI PowerMacs and PCI PowerBooks. PCI-based Apple Clones should also be supported.
Genesi Pegasos I/II, Open Desktop Workstation, Efika
IBM RS/6000, iSeries, pSeries
Requirements
Memory At least 64 MB
Diskspace 1.5 GB (excluding swap space)
Swap space At least 256 MB

Be sure to read the Gentoo PPC FAQ for help with some common installation related issues or to know just what's in that PowerPC machine.


Gentoo Linux installation media

Tip
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 occasional Gentoo LiveDVD

Occasionally, a special DVD image is crafted which can be used to install Gentoo. The instructions in this chapter target the Minimal Installation CD, so things might be a bit different when booting from the LiveDVD. However, the LiveDVD (or any other official Gentoo Linux environment) supports getting a root prompt by just invoking sudo su - or sudo -i in a terminal.

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/ppc/autobuilds/ on any of the official Gentoo mirrors. Stages are updated frequently and are therefore not included within official live images.

Tip
For now, stage files can be ignored. They will be described in greater detail later when they are needed
Note
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.

Navigating Gentoo mirrors

If downloading from a mirror, the minimal installation CDs can be found by:

  1. Connect to the mirror, typically using a local one found at Gentoo source mirrors.
  2. Navigate to the releases/ directory.
  3. Select the directory for the relevant target architecture (such as ppc/).
  4. Select the autobuilds/ directory.
  5. 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.
Note
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:

CODE Example list of downloadable files at releases/amd64/autobuilds/current-install-amd64-minimal/
[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.

Tip
The .DIGESTS file is only needed if the signature in the .iso.asc file is not verified.

Verifying the downloaded files

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

Tip
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 13EBBDBEDE7A12775DFDB1BABB572E0E2D182910
gpg: 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.org
gpg: 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.asc
gpg: 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.asc
gpg: 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.

Note
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 #lsblk
sdd           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.

Tip
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
Warning
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 && sync
Note
if= specifies the input file, of= specifies the output file, which in this case, is a device.
Tip
bs=4096 is used as it speeds up transfers in most cases, status=progress displays transfers stats.

Burning a disk

See also
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-ppc-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.

Booting

Default: Booting the installation CD with yaboot

On NewWorld machines place the Installation CD in the CD-ROM and reboot the system. When the system-start-bell sounds, simply hold down the c until the CD loads.

After the installation CD loaded, a boot prompt will show up at the bottom of the screen.

We provide one generic kernel, ppc32. This kernel is built with support for multiple CPUs, but it will boot on single processor machines as well.

It is possible to tweak some kernel options at this prompt. The following table lists some of the available boot options you can add:

Boot option Description
video This option takes one of the following vendor-specific tags: nvidiafb, radeonfb, rivafb, atyfb, aty128, or ofonly. Follow this tag with the resolution refresh rate and color depth to use. For instance, video=radeonfb:1280x1024@75-32 will select the ATI Radeon frame buffer at a resolution of 1280x1024 with a refresh rate of 75Hz and a color depth of 32 bits. When uncertain about what to choose, and the default doesn't work, video=ofonly will most certainly work.
nol3 Disables level 3 cache on some PowerBooks (needed for at least the 17")
dofirewire Enables support for IEEE1394 (FireWire) devices, like external hard disks.
dopcmcia To use PCMCIA devices during the installation (like PCMCIA network cards) this options needs to be enabled.
dosshd Starts the SSH daemon. Useful for unattended installs.
passwd=foo Sets the value after the = as the root password. Use with dosshd for remote installs.

To use the above options, at the boot prompt, type ppc32 followed by the desired option. In the example below, we'll force the kernel to use the Open Firmware framebuffer instead of the device specific driver.

boot:ppc32 video=ofonly

If no options are needed, just type ppc32 at this prompt, and a complete Gentoo Linux environment will be loaded from the CD.

Alternative: Booting the installation CD on a Pegasos system

On the Pegasos simply insert the CD and at the SmartFirmware boot-prompt type cd /boot/menu.

bootcd /boot/menu

This will open a small bootmenu that allows users to choose between several preconfigured video configs. Any special boot options can be appended to the command-line just like with Yaboot above. For example:

bootcd /boot/pegasos video=radeonfb:1280x1024@75 mem=256M

The default kernel options (in case something goes wrong) are preconfigured with console=ttyS0,115200 console=tty0 init=/linuxrc looptype=squashfs loop=/image.squashfs cdroot root=/dev/ram0.

Alternative: Booting the installation CD with BootX

With an OldWorld Mac the bootable portion of the livecd can't be used. The most simple solution is to use MacOS 9 or earlier to bootstrap into a Linux environment with a tool called BootX.

First, download BootX and unpack the archive. Copy the the BootX Extension from the unpacked archive into Extensions Folder and the BootX App Control Panel into Control Panels, both of which are located in the MacOS System Folder. Next, create a folder called "Linux Kernels" in the System folder and copy the ppc32 kernel from the CD to this folder. Finally, copy ppc32.igz from the Installation CD boot folder into the MacOS System Folder.

To prepare BootX, start the BootX App Control Panel. First select the Options dialog and check Use Specified RAM Disk and select ppc32.igz from the System Folder. Continue back to the initial screen and ensure that the ramdisk size is at least 32000. Finally, set the kernel arguments as shown below:

CODE BootX kernel arguments
cdroot root=/dev/ram0 init=linuxrc loop=image.squashfs looptype=squashfs console=tty0
Note
The kernel parameters in the yaboot section above are also applicable here. Append any of those options to the kernel arguments above.

Check once more to make sure the settings are correct and then save the configuration. This saves typing just in case it doesn't boot or something is missing. Press the Linux button at the top of the window. If everything goes correctly, it should boot into the Installation CD.

Setting the keyboard map

After boot, a root ("#") prompt appears on the current console. It is possible to switch to other consoles by pressing Alt + F2, Alt + F3 and Alt + F4. Get back to the first one by pressing Alt + F1. Due to the keyboard layout, it may be necessary to press Alt + fn + F# on Apple machines.

When installing Gentoo on a system with a non-US keyboard, use loadkeys to load the keymap for the keyboard. To list the available keymaps, execute:

root #ls /usr/share/keymaps/i386

Now load the keymap of choice:

root #loadkeys be-latin1


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 8139too

Optional: 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 #passwd
New 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 john
New 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 - john

Optional: 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 principal 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:PPC

To go back to the original terminal, press Alt+F1.

Tip
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 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 start
Note
If 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.