Firstly, I would like to thank mingdao, of techfix (under construction as this article was written). He reviewed this for me, catching several things that I'd missed.

The Gentoo handbook's installation section has a wealth of information, including installing with MBR, using systemd, an introduction to customizing the install to match your CPU, etc.

This guide, however, skips much of that. It's aimed at people who, perhaps, want to just install Gentoo, get a taste of it, and get into the heavier customization after they're more familiar with it. Or perhaps the more experienced Gentoo user who just wants a quick reference.

At any rate, this covers a fairly simple Gentoo install, on a wired network, using OpenRC for init and a UEFI boot. By the end of it, you should have a working Gentoo system that you can then build upon, to make use of Gentoo's many ways of customizing a system to suit your needs.

My example is being done on a FreeBSD bhyve virtual machine, so the disk uses the name vda. Change your disk name according to what you're using, e.g., sda or nvme.

First Steps

more /etc/motd

This gives the official start message and we'll cover some of this. We'll do a couple of things differently though. You'll also see the message when you login with ssh, which we'll do shortly.

First we connect to the network. If you're using a wired connection, there's a good chance it's already working with a DHCP address. For more complex setups, see the handbook's networking page. In my case I have a wired connection, but I want to give it a static IP. I use a router with an IP of 192.168.1.1.

I run the command ip a and see that my card is seen as enp0s5

ip addr add 192.168.1.175/24 dev enps05 ip route add default via 192.168.1.1

I have another machine on the network set up as a nameserver so I edit /etc/resolv.conf.

nameserver 192.168.1.146

Although Gentoo's DHCP saw and set my /etc/resolv.conf, it chose the wrong one, so I manually set it. 192.168.1.175 is the IP I'm giving the Gentoo install, and 192.168.1.146 is my LAN's nameserver. I test that it's working with ping gentoo.org and if I get a ping back, I can be confident that my Internet works.

Next, I set a password, so that I can do the rest of the install remotely. With Gentoo, one can use the root user, so I just set its password with passwd. I'm asked to enter it again for confirmation. This password will only be used for installation, we'll have to reset it before rebooting. Next I fire up sshd so that I can ssh into the machine.

rc-service sshd start

Now I can ssh into the machine, with ssh root@192.168.1.175 and do what I need to do.

Preparing the disk

gdisk /dev/vda
o (this clears the disk of any existing partitions)
y (to agree that you want to clear partitions)
n (create a new partition).

It will then ask which partition, hitting enter for default is partition 1. For start, accept the default, then for partition end hit +1G to make it one GB in size. The next entry shows the default hex code, 8300 for Linux, but enter EF00. It will then show you have one EFI partition.

Hit enter again and it will ask to choose which partition, showing the default of 2. Hit enter and it will ask the starting point. Once again, hit enter to accept the default, and again, when it asks ending point enter +1G to make it 1 G in size. Hit enter and change the hex code to 8200. It will show there is a second partition as Linux swap.

Now once again hit enter, the default is partition 3, hit enter to accept that, and enter again to accept the default start point. Then enter again to take the default end, which is the rest of the disk. Hit enter again to accept default hex code of 8300, Linux.

Hit p to review what you have, it should show the 3 partitions you chose. Now you can hit w to write it. It will ask if you're sure, choose yes. We're done with partitioning, now on to formatting.

mkfs.vfat -F 32 /dev/vda1 mkswap /dev/vda2 mkfs.ext4 /dev/vda3

Make needed directories and mount the partitions. By default, there's already a /mnt/gentoo partition.

mount /dev/vda3 /mnt/gentoo mkdir -p /mnt/gentoo/efi mount /dev/vda1 /mnt/gentoo/efi swapon /dev/vda2

Getting the Stage3 Tarball

cd /mnt/gentoo
links https://www.gentoo.org/downloads

This opens links, a text based browser. You can, once it's opened, navigate down the page till you see the tarball for stage 3 openrc. You can also choose the openrc desktop profile version. As explained on the downloads page the desktop version already contains various programs needed for a typical desktop install. In practice, if you're eventually going to install X, this can save time. When you've chosen your version and hit enter, links will ask if you want to save it, so hit enter, and it should save. Now you can hit q to exit links. You're in /mnt/gentoo and you should see, if you do ls, a tarball for stage3 openrc.

tar xpvf stage3-*.tar.xz --xattrs-include='*.*' --numeric-owner -C /mnt/gentoo

You should see it untarring the xz file.

Installing the System

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

Now, chroot into the new system.

arch-chroot /mnt/gentoo export PS1="(chroot) ${PS1}"

If you don't use arch-chroot, there are several more directories to mount, as specified in the handbook.

Next, we'll get some necessary files and choose a profile, I'm using profile 3, a very general desktop one. To see all available, you can use eselect profile list, but I'm selecting profile 3. There is also the profile for very generic, profile 1, (profile 2 is for systemd desktop) but as the handbook points out, the various desktop profiles aren't necessarily just for a desktop install. The profile 1 is good if you're making a headless machine, or one where you don't plan to use X. It will make differences, for example, emerging vim uses several more packages with a desktop profile.

Now, to install vim. Vim is on the install cd, but you don't have it once you chroot, as that system only includes nano. I'm used to vi, and if I don't install it now, every file I edit will become full of j's and k's as I try to edit the file. We're also going to run getuto, as we're going to use the binary package for vim and getuto is to verify binary signatures.

emerge-webrsync eselect profile show getuto emerge --getbinpkg vim

The eselect profile show should show the default/linux/amd24/(version)/desktop. If it doesn't then do eselect profile list (I would pipe it to more or less as there's several), and eselect profile set with the number you choose, probably 3.

You can now call vim as vim or as vi, depending upon your choice and/or habit. I use vi, but if you do a ls -l you'll see that it's an alias for vim.

Now I want to edit /etc/portage/make.conf. I'm adding a preference to use binary packages, rather than building them all from source as well as accepting a couple of licenses. So, I run vi /etc/portage/make.conf and add these lines.

FEATURES="${FEATURES} getbinpkg" # Require signatures FEATURES="${FEATURES} binpkg-request-signature" ACCEPT_LICENSE="-* @FREE @BINARY-REDISTRIBUTABLE"

Configuring Your New System

ln -sf /usr/share/zoneinfo/America/New_York /etc/localtime

You want to set the locale. Edit /etc/locale.gen and choose your locale. English speakers in the US probably want en_US.UTF-8, so uncomment that in /etc/locale.gen, then run the command locale-gen. You will see it generating a few locales. You can list them with eselect locale list then choose what you want. I choose 4 as that's en_US.UTF-8.

eselect locale set 4

Afterwards there will be a message to run . /etc/profile. Do so. (If you're unfamiliar with it, the . /etc/profile is the same as using source /etc/profile, so make sure to put a space between the dot and /etc/profile). While we're at it, you can also set the default editor. The default is nano, so if you later use vipasswd or visudo, the file will open up in nano. So you can also run

eselect editor list

which gives a list, showing nano as the default, but also vi, vim, and ed. I choose vi which is number 3 at time of writing. So I run

eselect editor set 3

Once again you get a message to run . /etc/profile. Note that when you run . /etc/profile, you lose the PS1 prompt that you've had, so after running . /etc/profile, once again run

export PS1="chroot) ${PS1}"

Installing the Kernel and doing some configuration

mkdir -p /efi/EFI/Gentoo

Now I get various needed firmware and drivers. You can use emerge --ask to choose exactly what you want, but I usually just get the whole kit and caboodle. I'm getting the kernel at the same time. I use gentoo-kernel-bin, again you can look at the handbook to see if this is what you want but it works well for me.

emerge linux-firmware sof-firmware gentoo-kernel-bin

A couple of other small tasks. Say your calling this gentoo.example.com.

echo 'gentoo.example.com' > /etc/hostname

You'll also want to add the machine name to /etc/hosts. You'll see lines for 127.0.0.1 and ::1 (the ipv6 equivalent of 127.0.0.1) marked local host. Add in entries for the gentoo.example.com. You can just put it under the local host entries.

127.0.0.1 gentoo.example.com gentoo ::1 gentoo.example.com gentoo

I'm going to set my network as the same 192.168.1.175 I've been using for installation. So first I install netifrc

emerge netifrc

Then I edit, or create if needed, /etc/conf.d/net

config_enp0s5="192.168.1.175 netmask 255.255.255.0 brd 192.168.1.255" routes_enp0s5="default via 192.168.1.1"

Now, I set it to start at boot.

cd /etc/init.d ln -s net.lo net.enp0s5 rc-update add net.enp0s5 default

Don't forget to set the admin password, and add a user if you want. Users and passwords set up when you first booted the install CD won't be remembered. So, if needed, hit passwd and give yourself a password to log in after reboot. Create a user if desired as well.

useradd -m -G users,wheel,audio myuser passwd myuser

You can emerge sudo if you wish, or, if your user is in wheel, it can su to root.

A few more things before we do the bootloader. Install a logger, something for cron and something to keep time. We'll use sysklogd, cronie, and chrony. We'll also install bash-completion while we're at it.

emerge sysklogd cronie chrony bash-completion

We'll set the logging cron and time to start at reboot. Let's also get sshd running when the system starts.

for i in sysklogd cronie chronyd sshd;do rc-update add "${i}" default;done

Add the Boot Loader

emerge grub
grub-install --efi-directory=/efi

This should install with no errors reported. If it doesn't, the handbook suggests that you go to the the grub debugging page.

As I tend to spam my pages on FreeBSD forums, I'll mention that vm-bhyve can have issues, as it expects grub to be in certain places. I explain this in more detail on my vm-bhyve page, but if this is a vm on FreeBSD's bhyve, the install will be slightly different.

grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id=boot

Also, again, only if this is a FreeBSD bhyve vm, cd into the /efi/EFI/boot and copy grubx64.efi to bootx64.efi.

Now, configure grub. This should be straightforward.

grub-mkconfig -o /boot/grub/grub.cfg

At this point, you're done. Just exit out of chroot, umount the mounted partitions, and reboot.

exit cd umount -R /mnt/gentoo reboot

Well, hopefully, you now have a working Gentoo install, and can go to its handbook to see the many ways you can work with it.