XED’s Gentoo Installation Notes

Set the date if needed. This helps minimize confusion with package freshness.

Optional: It’s sometimes useful to not let the screen blank so you can keep a casual eye on the compiling processes. This is only necessary if you’re going to be installing at the console (in the ordinary way).

Optional: If you want to do the entire installation from somewhere else, just start the ssh server. The default password is randomly chosen so you must reset it.

The screen program allows some great tricks. First, with it, you can be doing one installation on one virtual terminal while looking at these notes on another. Ultimately, when you know what you’re doing, you can be working on two or more parts of the installation process at the same time. The advantage of this over just using the native Linux consoles (Alt-Fn) is that these vitual terminals can be switched when working remotely. The other immensely helpful thing screen does is that it allows you to start a big compile and then close that terminal. This is nice if you don’t want to leave a compile running on a public terminal or one that you want to use for other purposes. The "nohup" command can do this too, but screen is much better since with it you can bring sessions back to the foreground. This is most useful when, for example, starting an install at one location and then going to another to finish it.

Note that if screen itself gets reinstalled from source from within a screen session, it is likely that the session will be unavailable to the new screen program. I’ve been locked out of my update this way.

The same can be true for SSH. Make sure a new ssh doesn’t create a /etc/ssh/sshd_config that doesn’t have a yes for PermitRootLogin if needed.

For fancy robust RAID set ups where you have the system installed on two redundant drives, set up a RAID1 system. See my RAID notes for details.

Partition the drives.

Or whatever your drive/s is/are. Use dmesg | less to search for more complicated drive naming schemes like /dev/cciss/disc1/disc.

Set up a boot partition (this is optional and sometimes I find it to be more trouble than it’s worth). Best to make this ext2.

Format the main drive or drives.

Or mkfs.reiserfs is a good chioce too. Or use some formatted drives that are already full of Linux stuff. Do what you have to do. It’s your choice.

Format the swap space.

Or you can try not using any swap space at all. It’s kind of a weird concept and not necessarily helpful on small systems with SSD storage.

Why not utilize that swap space right now?

Gentoo disks tend to have this mount point. Mount main system’s drive.

Now that you’ve prepared the place this Gentoo installation will live, it is time to actually install Gentoo itself. There are a few ways to do this, but the easiest way for me is to unpack a big compressed tar file containing the main skeleton of the entire system. Gentoo has a notion of "stages". If you’re reading these instructions, you definitely want stage 3 which will include a few precompiled utilities in the skeleton (a compiled compiler, software for getting more software, etc) which will help get the ball rolling.

This stage 3 file is found on "Universal" Gentoo install disks. I tend to use "Minimal" install disks so I have to scrounge the web for them. Since you probably will be installing software from the Internet anyway, it’s not a bad scheme. If you don’t already have a stage 3 tar file, open a new screen terminal and run Twibright Links to look for a mirror (links google.html). Enter a search term like site:edu ftp mirror gentoo stages bz2. That should get you close You can download it with Twibright Links (press d), or:

Note that with some install CDs you might not have room to install it into the system directories. You may need to cd into the target volume. It’s ok for the tar file to be there in what will be the top / directory.

It’s very little trouble to see if the download went well. Consider it insurance:

Once you have the tar file in place where it can be used, upack it. This shows how it might be done if you didn’t have to go find a tar file, but were able to use one from a "Universal" installation CD.

Add a "-v" to watch the action (this is slower).

If you really want to be clever, then try some crazy thing like this:

Actually these days I just pick a mirror that still isn’t dead. This website shows live stats on the currently working mirrors.

https://mirrorstats.gentoo.org/distfiles/

Assuming there is a boot partition.

This should be done in preparation for switching to the new filesystem. Note that the dev one is required for virtual dev systems which is the norm these days. If you don’t do this, your devices will not be found at grub install time.

Note that the newish --make-rslave commands are needed for systemd.

Since you know the network works at this point and you can access both the installation filesystem and the new Gentoo one, go ahead and copy your DNS. Make this file’s permissions accessible or you’ll have weird host resolution problems when emerge uses wget. This is because things (wget, ping) resolve fine from the command line as root, but emerge runs as the portage user.

The make.conf used to live in /etc/make.conf but now lives in /etc/portage/make.conf.

These days I just copy a make.conf from a known good system and then edit it. If you don’t have that established yet, just follow the hints in the /usr/share/portage/config/make.conf.example file.

Sometimes you do need to make one from scratch. Here’s where to start looking for that.

It seems that the CHOST variable should pretty much not be messed with. Except in strange cases it should be this.

Note that a good CFLAGS value is something like this.

That’s pretty safe and adds all the compiler flags that your cpu supports. Obviously cross-compiling would need to think carefully about this.

This shows what kind of processor you’re working with which might come in handy when picking compile flags.

Check out this list of safe cflags for a good idea of what to put here.

Some important /proc/cpu "flags":

All this and a whole lot more!

Here’s a good starting point for a server’s make.conf.

In the past the GENTOO_MIRRORS variable in make.conf specified where the main ebuild tree was. While that variable isn’t completely gone, I don’t use it now. Instead the modern technique is to make a file like this.

Set mountpoints for your drives.

Something like this is typical:

This trick changes the current filesystem to be limited to (root changed) the file system the new Gentoo installation will use.

Now the system behaves a lot like the new installation will.

Problems? Maybe you have a 32 bit install CD trying to make a 64 bit installation. Try getconf LONG_BIT to check.

Pick the right one obviously. Then check that date again!

Time problems can sometimes be solved by emerging a new sys-libs/timezone-data.

If you need a proxy to fetch (wget) things, add this to /etc/profile.

Don’t forget the port the proxy accepts connections on. Apply these settings before building.

Double check that network is up and good. (Try using ssh or wget to test if firewall doesn’t allow ping (ICMP).

The following step creates the "portage" database. This is a complete list of what is available and how it needs to be installed. Notice that I preface most of these commands with the time command because I like to know how long all this takes.

The emerge command is part of the portage system. If there is an update to the portage system itself (since the version on the install disk - this is very likely), it is very wise to update the updater first thing.

Emerging typically downloads the source, compiles it, and puts it in the filesystem. Start by emerging the entire core system and kernel source.

Get the profile properly selected.

Before, after, or while getting the kernel situation under control, start the system installation:

If you’re installing on a slow machine, go to bed. Let sit overnight. Newer (dual Opteron, for example) machines can do this in a few hours.

I sometimes find on simple systems that the packages can all be installed by the time I’ve finished setting all the kernel options.

The technique to install packages basically uses the emerge command like this:

The -a is for --ask and is like a --pretend except that you are prompted to actually go for it or cancel. It’s pretty much always a good idea to use either -av or -pv when emerging stuff because it often shows you interesting things that your getting that you may not have wanted or compile options that are turned off that you actually would appreciate. To make temporary changes in compile options, you can do something like this:

It’s better to set these directives specifically by including them in the USE definition of the /etc/portage/make.conf file.

If you don’t know the name of a package you think exists, you can try something like:

You can also poke around in /usr/portage/*/ and see what you might like.

The thing to do now is find a bunch of packages you want and start them with a big emerge. Then switch over to another console and work on your kernel.

Actually, some of these packages I merely tolerate.

Selecting the correct kernel options can be bewildering. The trick is to make sure that you enable:

If you need to find out about your hardware, the kernel messages on the running system might be helpful.

Prepare servers and system daemons you wish to have running on this system. Customize this list to suit your needs. Nothing is critical here since you can add these later when you realize your running system is missing them.

Nothing more frustrating than getting a perfect Gentoo system working and then finding visudo or some such command runs an editor designed for children.

I think this is the old way:

The new way to set this correctly is to use the EDITOR and PAGER system variables.

Both EDITOR and PAGER are set by default in /etc/profile. You can change it there or change it locally in your own ~/.bashrc environment. Another option is to create a /etc/env.d/99editor and set the system default there. Or, do all of the above to really make damn sure you’ll never see that stupid editor ever.

Looks like eselect does this automatically, but if it doesn’t, here’s what it looks like.

It looks like grub2 is all the rage now. Moving on with progress here is how to install it.

Basically it’s like this:

Or scrap all that stupid crap and make your own simple configuration file. Note that Grub2 has a different configuration file format which looks like:

Double check your bootloader’s configuration. In simple cases a simple one may be ok.

If you’re doing a RAID1 setup with two non-RAID boot partitions (one on each disk) for low hassle bootability, now is a good time to mirror sda1 to sdb1 using something like:

If this doesn’t exist, import :r /boot/grub/grub.conf.sample from vim.

Install the bootloader using the grub shell.

Or you can install the bootloader using grub’s install script.

The root password is auto scrambled. The root password must be reset!

Edit /etc/locale.gen and uncomment the en_US.... lines (or whatever makes sense for your favorite language. Then run locale-gen. Easy.

If you just want the only NIC to use DHCP, don’t do anything since that is the default behavior. Otherwise networking settings are set with the following commands.

You can obtain a working template by doing something like this.

It seems that these days the old eclectic Unix networking tools (ifconfig,route,arp,netstat) have a modern unified equivalent in the iproute2 package (ip addr, ip route, ip neigh, ss). It might be a good idea to emerge that package and let the network scripts use it.

An easy configuration looks like this:

Sometimes there is a hang on boot where the message stops after printing the hostname for about 20 seconds. This can be a problem in looking up the hostname. The way I cured this is to have an entry for the machine in the /etc/hosts file that looks like this.

It seems important to have the IP, the FQDN, and then an alias.

It is probably a good idea to emerge net-dns/bind-tools to get things like the host command. If you emerge net-dns/host you’ll get an executable called host-woods which may not be what you’re after.

Get out of the chroot situation.

Unmount all the drives because that is the nice thing to do.

If you have umounting trouble, i.e. "device is busy" and you know it’s not busy, use the -l flag.

You’re kind of finished in an abstract way. It’s usually a good idea to pull your install CD out of the drive now.

If you have trouble with the new kernel failing, you might be able to help things along with some kernel parameters.

Also if kernel messages fly by too quickly, consider adding boot_delay=100 to the kernel line. Or send it out a serial port.

Here are some of my personal troubleshooting tips and reminders. If more detailed help is needed see the official troubleshooting guide.

After updating there are often a lot of little broken things to fix. For many of these things the problem is so well-known and routine that there is a special utility for cleaning up the problem.

Sometimes it is helpful to install an intermediate version of a package that breaks during emerging. To find out which packages are possible, use eshowkw glibc (using glibc as an example package). Or try equery list -p glibc. Then something very specific like emerge =sys-libs/glibc-2.15-r3.

With the fact that Gentoo’s emerge is written in Python and Python 2 is very different from Python 3, there can be some issues with Python. Gentoo allows different versions of Python to co-exist peacefully. If Python issues are causing trouble, read the Gentoo Python User’s Guide.

Binary packages seem like a bit of an anti-Gentoo idea since the whole point of Gentoo is that the packages are not binary. But the critical idea of Gentoo is that your system shall be the way you want it. If that means all of the reasonable advantages of binary packages, then have fun. Binary packages are especially useful when trying to install on a machine with extremely limited processing power or other resources, basically when a machine can do what it is supposed to but not compile an OS. The other obvious use case is when you have replications of the same machine over and over. To recompile all software from scratch is simply a waste of electricity if the desired resulting binaries will be identical. I’m finding that VMs provide an excuse with respect to both of these issues.

Here is the official guide to using binary packages.

http://www.gentoo-wiki.info/HOWTO_Setup_local_Portage_and_Package_Mirror

In the past one used the SYNC variable in /etc/portage/make.conf like so.

Today you need to make a file like this instead (yup, comment that out of make.conf).