Installation alternatives
- Verify & validate these methods
- A few more details and references would be helpful
- Better wording
This article offers alternative installation techniques for systems or situations with special requirements, such as being unable to boot from a live environment due to lack of optical media hardware or USB port interfaces.
If the standard install method "boot from live image" cannot be used, or if another method is preferred, there are other methods to get an environment suitable from which to install Gentoo.
If additional alternative installation methods are found to be useful, please mention them in this article!
Installation from non-Gentoo live environments
The only fully supported method for installing Gentoo is with the Minimal Install CD. That said, installing from another, recent, live environment will usually work just as well. Gentoo support will often still be forthcoming using this method, but be ready to revert to the Minimal Install CD, if needed. Of course, in case of issues with other distributions, users will be referred to other channels for help.
The Handbook is regularly tested to check for installation issues using non-Gentoo media and it is now generally considered safe to follow on distributions as old as Debian Jessie. Please do report issues in #gentoo-wiki (webchat) if it is found to no longer be the case.
Once chrooted, and with an appropriate stage tarball, these live images can provide a functional environment to use for compiling and installing Gentoo. These instructions should, in principle, work with most recently created Linux live environments.
There are many LiveCDs out there, one example being Knoppix (available for x86 and amd64).
If anything is saved in the LiveCD's home directory while waiting for the Gentoo system to install, it will not be available when rebooting into Gentoo. Be sure to save important files on the hard disk or on some other computer!
Boot from the LiveCD. Open a terminal and run su - so the password can be changed. This allows to set the root password for the CD. The sshd daemon can now be configured for remote login if required. Next, create the /mnt/gentoo mount point:
root #
mkdir /mnt/gentoo
At this point, the standard install documentation can be picked up at Preparing the Disks. However, when asked to mount the proc system, issue the following command instead:
root #
mount -o bind /proc /mnt/gentoo/proc
When unpacking the stage tarball in Unpacking the stage tarball, be sure to use the following tar command options to ensure that proper group IDs are enforced on the unpacked stage:
root #
tar --numeric-owner --xattrs -xvJpf stage3-*.tar.xz -C /mnt/gentoo
For some distributions, such as Ubuntu, pay particular attention to the warning in the Mounting the necessary filesystems section of the handbook. bug #496328 may be of interest if issues are still encountered.
Once ready to chroot into the unpacked stage in Installing Base System, a different chroot command sequence will need to be used. This ensures that the environment variables are properly setup.
Some LiveCDs use a funny environment setup, hence the env -i option for cleaning it up to a reasonable state.
root #
chroot /mnt/gentoo /bin/env -i TERM=$TERM /bin/bash
root #
env-update
root #
source /etc/profile
root #
export PS1="(chroot) $PS1"
Finally, know that some Portage FEATURES may not work in the LiveCD. Especially watch out for userpriv
and usersandbox
values. If there are errors, try disabling some or all of the optional FEATURES.
Diskless install using PXE from the LiveCD
This method is easier to configure than PXE boot based on iSCSI or NFS. Multiple machines can boot from the same set of images distributed via TFTP and can be easily extended to also work over HTTP or other protocol.
Having a nice router, or one capable of running open source firmware such as OpenWRT/LEDE, is one way to centralize TFTP and DHCP. Getting the firmware online can sometimes be an uphill battle.
Some other distributions including Fedora already distribute images needed to bootstrap a live, or installation, CD. With Gentoo, users need to extract files from the ISO.
root #
emerge --ask --oneshot app-cdr/cdrtools
mkdir -p /tftpboot/gentoo/
cd /tftpboot/gentoo/
isoname=/tftpboot/ISO-IMAGES/install-amd64-minimal-20210725T170534Z.iso
isoinfo -R -i ${isoname} -X -find -path /boot/gentoo && mv boot/gentoo kernel && rmdir boot
isoinfo -R -i ${isoname} -X -find -path /image.squashfs
# combine initrd + squashfs
(isoinfo -R -i ${isoname} -x /boot/gentoo.igz; (echo image.squashfs | cpio -H newc -o)) > network.igz
rm image.squashfs
ls -lhF kernel network.igz
These instructions may be sufficient for more experienced users. See below for more directions, depending on the PXE flavor in use. There are different PXE boot-codes, but all of them require a kernel and eventually a ramdisk.
Please take a look at PXE page for details on the alternatives, then come back here.
TFTP
This will be needed in tandem with a DHCP server for most PCs equipped with PXE boot. However, iPXE may be used to boot without a TFTP or DHCP server - see ipxe.org for info on embedding scripts, chainloading, and manual booting. There are still merits to TFTP booting such as wide-range device support.
Install net-ftp/tftp-hpa, make sure it serves /tftproot and start it.
Now the TFTP boot service is ready, so the next step is to configure a DHCP service.
DHCP
Setting up a DHCP server on the same machine is possible - just make sure that the booted machines are connected to it. Or just tweak the configuration of an existing router.
Example configuration for OpenWRT DHCP service follows:
config boot linux
option filename boot/grub/i386-pc/core.0
option servername boot
option serveraddress 84.246.161.86
From here, directions will change depending on the PXE boot-code (i.e. SYSLINUX, GRUB, iPXE).
SYSLINUX
label gentoo install (squashfs/http)
kernel gentoo/kernel
initrd gentoo/network.igz
append root=/dev/ram0 init=/linuxrc dokeymap looptype=squashfs loop=/image.squashfs cdroot net.ifnames=0
GRUB
menuentry "gentoo install" {
linux /gentoo/kernel root=/dev/ram0 init=/linuxrc dokeymap looptype=squashfs loop=/image.squashfs cdroot net.ifnames=0
initrd /gentoo/network.igz
iPXE
#!ipxe
menu PXE
item --gap LAN
item gentoo gentoo install (squashfs/http)
:gentoo
kernel kernel root=/dev/ram0 init=/linuxrc dokeymap looptype=squashfs loop=/image.squashfs cdroot net.ifnames=0 initrd=network.igz
initrd network.igz
boot
Diskless install using PXE boot and NFS
Requirements
PXE (Preboot eXecution Environment) is a method for booting computers over a PXE-capable network interface (and using a PXE-supporting BIOS). In case the system does not support PXE boot from the network interface or BIOS, PXE can also be used as a boot method from block devices (like CDs or USBs). In such cases, a minimal boot environment mimics the PXE supporting network card (see also Etherboot/gPXE).
Server base setup
Create directories: The first thing to do is to create the directories where the diskless system will be stored. Create a directory called /diskless which houses a directory for each diskless client. For the remainder of this howto, the client that is being worked on will be called 'eta'.
root #
mkdir -p /diskless/eta
DHCP and TFTP setup: The client will get boot information using DHCP and download all the required files using TFTP.
For dhcpd, just run emerge dhcp (or any other DHCP server of choice). Make sure that the correct interface is selected in /etc/conf.d/dhcpd, and configure it accordingly. Then, add the following on /etc/dhcp/dhcpd.conf.
This provides a static IP address for the client and the path of a PXE boot image, here pxegrub. The MAC address of the ethernet card of the client in the example has to be replaced with the correct MAC address, as well as the directory where the client files will be stored.
option option-150 code 150 = text ;
ddns-update-style none ;
host eta {
hardware ethernet 00:00:00:00:00:00;
fixed-address ip.add.re.ss;
option option-150 "/eta/boot/grub.lst";
filename "/eta/boot/pxegrub";
}
Next configure the interface in /etc/conf.d/net so that it doesn't get cleared at bootup. See /usr/share/doc/openrc-*/net.example.bz2 for more information.
config_eth0="noop"
For TFTP, emerge net-ftp/tftp-hpa. In /etc/conf.d/in.tftpd, put the following:
INTFTPD_PATH="/diskless"
INTFTPD_USER="nobody"
INTFTPD_OPTS="-u ${INTFTPD_USER} -l -vvvvvv -p -c -s ${INTFTPD_PATH}"
Emerge GRUB:
root #
emerge --ask sys-boot/grub
Once GRUB is compiled, create the diskless client's boot directory:
root #
grub2-mknetdir --net-directory=/diskless/eta
Original way was to copy the PXE image to the diskless client but the path does not seem to exit anymore.
root #
mkdir /diskless/eta/boot
root #
cp /usr/lib/grub/pxegrub /diskless/eta/boot/pxegrub
Then edit its grub.lst config file.
root #
nano -w /diskless/eta/boot/grub.lst
default 0
timeout 30
title=Diskless Gentoo
root (nd)
kernel /eta/bzImage ip=dhcp root=/dev/nfs nfsroot=ip.add.re.ss:/diskless/eta
# For the nfsroot option, the IP address is the one of the server and
# the directory is the one where the diskless client files are located (on the server).
NFS is quite easy to configure. The only thing that has to be done is to add a line on the /etc/exports config file:
/diskless/eta eta(rw,sync,no_root_squash)
One important thing to do now is to modify the /etc/hosts file to fit requirements.
127.0.0.1 localhost
192.168.1.10 eta.example.com eta
192.168.1.20 sigma.example.com sigma
Creating the system on the server
A next step is to reboot the server with a Gentoo installation CD (although experienced administrators can continue without if they are sufficiently versed in Gentoo installations). Follow the standard install procedure as explained in the Gentoo Handbook BUT with the following differences: when mounting the file system, execute the next step (where sdaX is the partition where the /diskless directory was created).
root #
mount /dev/sdaX /mnt/gentoo
Mounting any other partition is not needed as all of the files will reside in the /diskless/eta directory.
This example uses a stage3 tarball. Mount /proc to the diskless directory and chroot into it to continue with the install. Then follow the installation manual until kernel configuration.
Be very careful when extracting the stage tarball to its destination, so as to not end up extracting over an existing installation.
root #
cd /mnt/gentoo/diskless/eta/
root #
tar -xvjpf /mnt/cdrom/gentoo/stage3-*.tar.bz2
root #
mount -t proc /proc /mnt/gentoo/diskless/eta/proc
root #
cp /etc/resolv.conf /mnt/gentoo/diskless/eta/etc/resolv.conf
root #
chroot /mnt/gentoo/diskless/eta/ /bin/bash
root #
env-update
root #
source /etc/profile
When doing the make menuconfig of the kernel configuration, don't forget to enable the following options with the others recommended into the install guide.
- The network card device support
(In the kernel, *not* as a module!)
-*- Networking support --->
Networking options --->
[*] TCP/IP networking
[*] IP: kernel level autoconfiguration
[*] IP: DHCP support
[*] IP: BOOTP support
File systems --->
[*] Network File Systems --->
<*> NFS file system support
[*] Provide NFSv3 client support
[*] Root file system on NFS
Save the kernel in the chrooted / (not in /boot) according to the pxegrub setting defined earlier. Next configure the diskless client's /etc/fstab.
/dev/cdroms/cdrom0 /mnt/cdrom iso9660 noauto,ro 0 0
Now to prevent the client from running a filesystem check:
root #
touch /fastboot
root #
echo "touch /fastboot" >> /etc/conf.d/local.start
Install net-fs/nfs-utils since the client will heavily depend on it:
root #
emerge --ask net-fs/nfs-utils
Do not install another bootloader because there is already one - pxegrub. Simply finish the install and restart the server. Start the services that are needed to boot the new client: DHCP, TFTPD, and NFS.
root #
service dhcp start
root #
service in.tftpd start
root #
service nfs start
Booting the new client
For the new client to boot properly, the BIOS and the network card need to be configured to use PXE as the first boot method - before CD-ROM or floppy. For help with this consult the hardware manuals or manufacturers website. The network card should get an IP address using DHCP and download the GRUB PXE image using TFTP. Then, a nice black and white GRUB bootmenu should be displayed from where users can select the kernel to boot and press the Enter (Return) key. If everything is okay the kernel should boot, mount the root filesystem using NFS and provide a login prompt. Enjoy.
Installing Gentoo from an existing Linux distribution
The only fully supported method for installing Gentoo is with the Minimal Install CD. That said, installing from another, recent, live environment will usually work just as well. Gentoo support will often still be forthcoming using this method, but be ready to revert to the Minimal Install CD, if needed. Of course, in case of issues with other distributions, users will be referred to other channels for help.
Requirements
In order to install Gentoo from an existing Linux distribution it needs to have the chroot command installed, and have a copy of the Gentoo installation or ISO that's desired to install. A network connection is needed to download files during the installation.
Overview
- First allocate a partition to Gentoo by resizing an existing Linux partition.
- Mount the partition.
- Choose an appropriate stage tarball and unpack it to the partition that is mounted.
- Configure compile options for Portage.
- Mount the necessary filesystems and chroot inside the pseudo-system.
- After entering the new environment, follow Gentoo Handbook from Mounting the boot partition to the end.
How to make space for Gentoo?
The root partition is the filesystem mounted under /. The first example shows the output of mount on a system. The second example uses df (disk free) to see how much space there is left and how it will be resized. Note that resizing the root partition is not mandatory! Anything else supported by the resizer can be resized, but let's talk about that later.
root #
mount
/dev/sdb2 on / type ext3 (rw) none on /proc type proc (rw) none on /dev/pts type devpts (rw,gid=5,mode=620) none on /dev/shm type tmpfs (rw,nodev,nosuid,noexec)
root #
df -h
Filesystem Size Used Avail Use% Mounted on /dev/sdb2 4.0G 1.9G 2.4G 82% / none 38M 0 38M 0% /dev/shm
As can be seen, the partition mounted as / named /dev/sdb2 has 2.4 GB free. In this case, it was decided to be resized as to leave 400 MB of free space, therefore allocating 2 GB for Gentoo. Not bad, it could have quite some stuff installed. However, 1 GB is deemed enough for most users. So now partition this thing!
Using parted to resize partition
sys-block/parted is extremely useful for resizing partitions. It is included on the Minimal installation CD.
There are other tools for doing resize of partitions as well, but an elaborate description of these tools is outside the scope of this guide.
Look up on that page the type of file system to resize and see if parted can do it. If not, some partitions might need to be destroyed to make space for Gentoo. Go ahead downloading the software and install it. In the next step, a problem arises: the Linux root partition needs to be resized, therefore a boot medium with a minimal Linux system must be booted in order to resize /. If the partition can be unmounted while still running in Linux then the following steps are not needed. Just install sys-block/parted and run it on a chosen unmounted partition to resize. Here's how it was done on this system.
Make sure that the operations that are required for partitioning are supported by parted!
Note again that Linux is synonym of "There's one more way to do it". The objective is to run parted on an unmounted partition so it can do its work. This step might not even be needed to do at all: there may only be the need to umount the filesystem to repartition in the Linux session and run parted on it.
Time to reboot and resize the partition. Do this only after taking a quick look at the parted documentation on the GNU website. The resize can be long for large hard-drives, be patient. Reboot the system with the Minimal installation CD. Run parted to be able to resize the partition. Once this lengthy process is done, continue with installing Gentoo. Reboot back into the old Linux system for now. The drive to operate on is the drive containing the partition that is going to be resized. For example, if the partition to be resized is /dev/sda3, the drive is /dev/sda.
root #
parted
(parted)
print
Disk geometry for /dev/sdb: 0.000-9787.148 megabytes Disk label type: msdos Minor Start End Type Filesystem Flags 1 0.031 2953.125 primary ntfs 3 2953.125 3133.265 primary linux-swap 2 3133.266 5633.085 primary ext3 4 5633.086 9787.148 extended 5 5633.117 6633.210 logical 6 6633.242 9787.148 logical ext3
(parted)
help resizepart
resizepart NUMBER END resize partition NUMBER NUMBER is the partition number used by Linux. On MS-DOS disk labels, the primary partitions number from 1 to 4, logical partitions from 5 onwards. END is disk location, such as 4GB or 10%. Negative value counts from the end of the disk. For example, -1s specifies exactly the last sector.
(parted)
resizepart 2 3133.266 4000.000
Be patient! The computer is working! Just look at the hard drive LED on the case to see its activity. This should take between 2 and 30 minutes.
Once the resize has finished, boot back into the old Linux as described. Then go to The Gentoo Handbook: Preparing the Disks and follow the instructions.
Chrooting
When chrooting, use the following command to flush the environment:
root #
env -i HOME=$HOME TERM=$TERM chroot /mnt/gentoo /bin/bash
root #
/usr/sbin/env-update
root #
source /etc/profile
The rest of the instructions are the same as Gentoo Handbook. Enjoy!
Booting ISO from a bootloader
The default installation method is to burn the installation media to a USB drive. This way one has to dedicate an entire drive for installation. Instead one can use a bootloader to boot an ISO image saved as an ordinary file in a filesystem, or saved in one partition. It can also be used as a rescue medium after installation.
Using GRUB
In this section we describe Grub configuration.
The point is to extract the kernel boot options and the initramfs option from the iso image. To identify them, mount the iso file somewhere, and read the grub.cfg:
root #
mount -o loop <iso file> <some>/<directory>/
root #
cat <some>/<directory>/boot/grub/grub.cfg # typically here
... linux /boot/gentoo overlayfs nodhcp looptype=squashfs loop=/image.squashfs cdroot initrd /boot/gentoo.igz ...
Two steps are necessary. First, you have to specify the loopback device, like this:
if [ x$feature_platform_search_hint = xy ]; then
search --no-floppy --fs-uuid --set=isopart --hint-bios=hd0,gpt10 --hint-efi=hd0,gpt10 dccf78a8-6456-4c81-ada8-26e7bc739b53
else
search --no-floppy --fs-uuid --set=isopart dccf78a8-6456-4c81-ada8-26e7bc739b53
fi
set isofile="/<iso file image location>"
loopback loop ($isopart)$isofile
For a complete instruction, see the grub documentation. Here, the partition of the filesystem is specified, and isofile
is the path to the iso file. Next, modify the above original configuration of the iso image as:
linux (loop)/boot/gentoo overlayfs nodhcp looptype=squashfs loop=/image.squashfs cdroot isoboot=$isofile
initrd (loop)/boot/gentoo.igz
i.e. prepend (loop)/
to the two lines, and also add isoboot=
to the boot option.
Then wrap all inside menuentry{...}
block in the file /etc/grub.d/40_custom
and generate grub.cfg as usual.
This method was reported to work for the Jan 2024 iso image. (There the difficulty of using an iso image in a filesystem under lvm was mentioned. This can be bypassed by avoiding lvm.) The ArchLinux Wiki article Multiboot USB drive might help.
rEFInd
To boot an ISO image from rEFInd, see the page rEFInd.
See also
- Installation — an overview of the principles and practices of installing Gentoo on a running system.
- Install Gentoo on a bootable USB stick — describes how to install Gentoo onto a USB stick that can be booted on any computer.
This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Gerald Normandin Jr., Travis Tilley, Oleg Raisky, Alex Garbutt, Alexandre Georges, Magnus Backanda, Faust A. Tanasescu, Daniel Ahlberg, Ken Nowack, Tiemo Kieft, Benny Chuang, Jonathan Smith, and
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.