From Gentoo Wiki
Jump to: navigation, search

In this page I collect my slightly different ways of installing Gentoo for various environments. I'm maintaining it for myself, so feel free to read it but don't forget that there's official documentation.

Prepare installation media


Upstream status:

  • PXE images not distributed
  • PXE documentation uses NFS, not squashfs, entirely wrong for a live system

Manual way:

  • grub2-mknetdir -v --net-directory=/tftproot
  • download install-amd64-minimal-20141204.iso
  • mount the iso
  • modify initrd and merge in squashfs
  • create grub.conf

Created a script and documented in Gentoo Wiki:

Publish over tftp:

emerge -av tftp-hpa
systemctl enable tftp.socket (check /tftproot location)

Configure DHCP server


Boot the live system

My goal in this section is to get you booted as quickly as possible with a bare minimum of packages installed in the proces.

Note: I recently heard about Stage7 which has a potential of getting you there even faster but I haven't tried it, yet.


Use PXE boot to start the live system. It may take quite some time and no progress information is displayed by GRUB.

Optional: Obtain remote access


/etc/init.d/sshd start
mkdir .ssh
curl -o .ssh/authorized_keys "$key_url"
chmod 600 .ssh/authorized_keys
ip address

Connect over SSH:

ssh root@<my-ip-address>

Alternative: SSH without host keys.

alias issh="ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no"
issh root@

Configure and mount storage

Format disks – Single disk laptop:

echo -n "o.n.....w." | tr . "\n" | fdisk /dev/sda
pvcreate /dev/sda1
vgcreate -s 1G vg /dev/sda1

lvcreate vg -n gentoo -L 64G
lvcreate vg -n home -L 64G

mkfs -t ext4 /dev/vg/gentoo
mkfs -t ext4 /dev/vg/home
mkswap /dev/vg/swap

mount /dev/vg/gentoo /mnt/gentoo
mount /dev/vg/home /mnt/gentoo/home

Format disks – Storage server with four disks:

for i in a b c d; do echo -n "o.n.....w." | tr . "\n" | fdisk /dev/sd$i; done
mdadm --create /dev/md0 --level=6 --raid-devices=4 /dev/sd[abcd]1
pvcreate /dev/md0
vgcreate -s 1G vg /dev/md0

lvcreate vg -n system -L 8G
lvcreate vg -n swap -L 8G

mkfs -t ext4 /dev/vg/system
mkswap /dev/vg/swap

mount /dev/vg/system /mnt/gentoo

Don't forget to configure your /etc/fstab with any filesystems including the rootfs.

Optional: Synchronize system time


Bug: The livecd already configures network, I have no idea why it doesn't also update the time.

Install and enter the base system

curl | tar -C /mnt/gentoo -xjp

mount -t proc proc /mnt/gentoo/proc
mount --rbind /dev /mnt/gentoo/dev
mount --rbind /sys /mnt/gentoo/sys
cp -L /etc/resolv.conf /mnt/gentoo/etc/
chroot /mnt/gentoo /bin/bash
source /etc/profile

Get current portage tree

emerge-webrsync && emerge --sync

Bug: emerge-webrsync complains about nonexistence of /usr/portage so that it looks as if it failed but it didn't.

# emerge-webrsync
!!! Section 'x-portage' in repos.conf has location attribute set to nonexistent directory: '/usr/portage'
!!! Section 'gentoo' in repos.conf has location attribute set to nonexistent directory: '/usr/portage'
!!! Invalid Repository Location (not a dir): '/usr/portage'
Fetching most recent snapshot ...

Select profile (laptop with systemd)

Set profile (systemd laptop):

eselect profile set default/linux/amd64/13.0/desktop/gnome/systemd

Optional: Switch /tmp and /var/tmp to tmpfs

CODE /etc/fstab
none                    /tmp            tmpfs
mount -a
rm -rf /var/tmp
ln -s /tmp /var/tmp

Configure and build kernel

Get kernel and initramfs tools (Laptop with systemd):

emerge gentoo-sources genkernel-next

Note: Classic genkernel has been masked in the systemd profile. Note: lvm2 gets installed as a dependency. Bug: It indirectly hard depends depends on boost which takes ages to build.

Get kernel and initramfs tools (Storage server):

USE=-thin emerge --ask gentoo-sources genkernel mdadm lvm2

Build kernel and initramfs:

for option in MENUCONFIG CLEAN MRPROPER MDADM LVM; do sed -ri "s/^#?$option=.*/$option=\"yes\"/" /etc/genkernel.conf; done
genkernel all

Bug: I had to add --no-zfs to build the initramfs.

In the menuconfig (laptop): enable systemd support in kernel

  • Bug: systemd works without it but cryptsetup/fstab ordering fails! apparently

systemd wasn't able to learn about the completed cryptsetup.

enable kms by default to get good VT resolution and working X11

  • Bug: xorg won't start otherwise
  • Bug: screen wouldn't go back on after sleep on Lenovo T540p

In the menuconfig (storage server):

No changes needed.

Configure and install bootloader

Install bootloader tools:

root #emerge --ask grub

Bug: On one of my installations, grub couldn't be installed without running perl-cleaner --all.

Install bootloader (laptop):

grub2-install /dev/sda

Install bootloader (storage server):

for i in a b c d; do grub2-install /dev/sd$i; done

Configure bootloader

sed -ri 's|^#?GRUB_CMDLINE_LINUX=.*|GRUB_CMDLINE_LINUX="domdadm dolvm resume=/dev/vg/swap"|' /etc/default/grub
grub2-mkconfig -o /boot/grub/grub.cfg


Install tools needed after reboot:

root #emerge --ask dhcpcd openssh net-misc/curl

Configure tools needed after reboot:


mkdir -p .ssh && curl -o .ssh/authorized_keys "$key_url" && chmod 600 .ssh/authorized_keys
sed -i 's/^UsePAM .*/UsePAM no/' /etc/ssh/sshd_config

When using OpenRC:

rc-update add dhcpcd default
rc-update add sshd default

See also:

Set root password:

root #passwd
root #reboot

Bug: You need to set the root password to enable the root account even if you're only going to log in remotely. You also need to set it if you want to be able to log in locally in emergency.

Configure the target system

Optional: Configure the build system and rebuild all packages

In ancient times, you could opt to install using the stage1 tarball, and would have all packages built with the build configuration you wanted. This is no longer supported by the Gentoo project. With the stage3 tarball installalation you have a good number of packages already built with the default configuration instead.

Warning: The rebuild process can be very time consuming and the optimizations may not even be significant. The default configuration is good enough for many use cases. Setting just the CPU_FLAGS_X86 to at least get advanced CPU features used by some software packages and running emerge -avDNu world is much faster, though.

Warning: Optimizing to a specific type of CPU may prevent you from easily moving the system to another machine. Default configuration or a broader set of CPUs (e.g. -march=core2 -mtune=corei7 instead of -march=corei7) may help.

Examine the hardware

Examine the system for CFLAGS and learn what gcc thinks about the target platform:

gcc -march=native -Q --help=target emerge --oneshot app-portage/cpuinfo2cpuflags cpuinfo2cpuflags-x86

Configure the build system

Configure CFLAGS and CPU_FLAGS_X86, add $CPU_FLAGS_X86 to USE, remove bindist and cpu flags from USE.

nano /etc/portage/make.conf

Rebuild all packages

It is the easiest way to get a system built with the above configuration but it may take a lot of time depending on your hardware. It is a good idea to clean up unnecessary packages before and after the process.

root #emerge --ask --depclean
root #/usr/portage/scripts/ && emerge --emptytree world
root #emerge --ask --depclean

Check for packages with old CFLAGS

The package CFLAGS are stored in /var/db/pkg/*/*/CFLAGS.

CODE grep -xFv -- "`portageq envvar CFLAGS`" /var/db/pkg/*/*/CFLAGS
/var/db/pkg/dev-lang/python-2.7.9-r1/CFLAGS:-march=btver1 -O2 -pipe -fwrapv
/var/db/pkg/dev-lang/python-3.3.5-r1/CFLAGS:-march=btver1 -O2 -pipe -fwrapv
/var/db/pkg/dev-libs/openssl-1.0.1k/CFLAGS:-march=btver1 -O2 -pipe -fno-strict-aliasing -Wa,--noexecstack
/var/db/pkg/sys-apps/busybox-1.23.1-r1/CFLAGS:-march=btver1 -O2 -pipe -fno-strict-aliasing
/var/db/pkg/sys-libs/glibc-2.19-r1/CFLAGS:-march=btver1 -pipe -O2 -fno-strict-aliasing -fno-stack-protector

My output shows a couple of packages with custom CFLAGS, none of them actually built with the old -march or anything like that.

Install and configure important gentoo packages

Now that we're not going to rebuild the whole system any more, it is time to add various other packages for everyday use. I'm using package sets to have common sets of packages used accross machines.

Create and install packages

root #mkdir /etc/portage/sets && nano /etc/portage/sets/my-gentoo
CODE /etc/portage/sets/my-gentoo

Note: The items that are commented out are either not installable in Gentoo stable environment (which I consider a bug) or not needed on all my systems.

root #emerge --ask --noreplace @my-gentoo

Enable power button on OpenRC systems:

root #emerge --ask acpid
root #rc-update add acpid default && /etc/init.d/acpid start

TODO: I'm considering creating an overlay just for the package sets.

Add overlays

root #layman -a ...

Build eix cache and update the system

root #eix-sync && emerge -avDNu world

Configure remote shell accounts

For each user, create a user account and set a dummy password so that SSH recognizes that the account is not locked and enter the user account using sudo.


useradd -m "$user"
echo -ne "$user:`pwgen 16`\n" | chpasswd
sudo -i -u "$user"

In the user account, configure SSH:


mkdir -p .ssh
curl -o .ssh/autorized_keys "$keyurl"

Enable bash completion

root #emerge bash-completion && eselect bashcomp enable --global {0..478}

See also:

Configure printing

Make sure Avahi is running and used per configuration of /etc/nsswitch.conf if you want to search for printers that support Mulitcast DNS.

root #systemctl enable cups && systemctl start cups
root #system-config-printer

Don't forget to adjust the paper size and set your printer as the default printer.

Configure per-user executable directory

echo 'export PATH=$HOME/bin:$PATH' > /etc/profile.d/
. /etc/profile

Turn off persistent device rules

ln -s /dev/null /etc/udev/rules.d/80-net-setup-link.rules

Install and configure virtualization tools

On server:

euse -p app-emulation/libvirt -E virt-network qemu
emerge libvirt bridge-utils
rc-config add libvirtd default && /etc/init.d/libvirtd start
rc-config add avahi-daemon default && /etc/init.d/avahi-daemon start
FILE /etc/conf.d/net
brctl_br0="setfd 0
sethello 10
stp off"
rc-config add net.br0 && rc-config start net.br0
rc-config delete dhcpcd

You will need to rebuild the kernel with appropriate options.

Bug: The libvirt package is not capable of reconfiguring the kernel.

On client:

USE="-pulseaudio -libvirtd -lxc -qemu" emerge -av virt-manager

Bug: Without use flag adaptation it installs more packages. But even with it, there's a lot of dependencies.

See also: