Contents

Why Gentoo? Why this?

Gentoo is one of the most Linuxy Linux distributions. That is to say if you like the things that make Linux what it is, you’ll probably like Gentoo. When I was installing Gentoo the first few times, I had the feeling that the procedure could be wrapped up in a script. But that isn’t quite right. If the procedure is simplified and automated, then you will inevitability suffer a limitation of possibilities. Gentoo tries hard to avoid the least common denominator effect by making you do everything explicitly. Realizing this, I thought that perhaps a more flexible script could be written to just prompt you as to what to do next. Then I realized that I had incidentally written such a script on a piece of paper in the form of these notes. So imagine that you’re being prompted by each item on this procedure in order without any limitations on your ability to do whatever you want in the ordinary Linux way.

Why Gentoo? Why this? Gentoo Philosophy

Gentoo is filled with delightful idiosyncrasies. To use Gentoo, you really have to know what you’re doing. Fortunately, since that’s a requirement by design, there is a lot of excellent help out there. And because knowing what’s going on is a requirement, the organization of the distribution is as unobfuscated as possible. For example, in any Linux distribution, you will eventually have to make configuration changes by editing some configuration file; given this fact, isn’t it reasonable to say that all configuration changes should be made in this way?

The first step is to generally know what you’re doing when you see a Unix command prompt. If the whole idea of a command prompt makes you feel like your choices are limited, then Gentoo may not offer much advantage to you. If you realize that a command line gives you all the power you could possibly have, then Gentoo will seem very clever and elegant. For example, when installing other distributions (SuSE for example), I sometimes use CTR-ALT-F2 to get to a text console to see if I can find out the cause of any problems I’m having. Gentoo makes that the default mode. The Gentoo philosophy is to not protect the user from the ability to solve problems.

Advantages and Disadvantages

Pro

  • Excellent on-line help.

  • Managed customizability of packages.

  • Great for minimal installations, specialty servers, etc.

  • Biggest collection of packages, i.e. biggest collection of software.

  • Ability to use experimental/development software is designed in.

  • Can be installed completely remotely! No boot disks needed.

  • You can use the system while installing.

  • Only have what you need/want. (See Krebs' Rule #1.)

  • Staying up to date is extremely easy. It can be automated for everything or specific packages.

  • Generally fast rebooting compared to other OSs.

  • Generally faster performance compared to other OSs.

  • Eliminates problems with non-native libraries.

  • Good support for non traditional chip architectures.

  • Makes it possible to better understand what is going on behind the scenes.

  • Compiling/installation is a good stress test before deploying a machine.

  • Nice text console organization. For example, excellent use of color.

  • Solves problem of how to upgrade a machine that must remain in service during the upgrade (perhaps with a different Linux).

  • System administration does not depend on fragile GUI tools.

Con

  • Obviously compiling an entire OS takes a while.

  • Possible abuse of disks from lots of compiling (in /var/tmp).

  • etc-update is not popular or fun… But there’s simply no easy way to deal with this problem.

  • Important messages get lost in a sea of non important compiler messages or zoom off the screen.

  • I’ve had various versions of Gentoo install disks totally hang during hardware detection on various machines. I usually am now prepared with a sysresccd and older install disks. One of those will work.

  • nano. I hate this idiotic editor. Gentoo is optimized for people who know what they’re doing - except for their choice of editor.

  • If your box is compromised, it may be harder or take longer to recreate a fancy highly customized Gentoo system. Other distros are much more disposable.

Installation Starting Point

Before you begin, you will need a computer and a way for that computer to get and store data. Really, that’s all that is strictly required. Ideally you want a USB key reading/booting ability and a connection to the Internet, though you can do without either. The most obvious way to get started is to get a Gentoo install CD image and burn it onto a CD and boot from that. But let’s say you don’t have a CD burner. That’s a problem, but unlike with other distributions (and certainly OS’s), that problem is not insurmountable.

One of the nice things about Gentoo is that it can be completely installed while running another OS. So from a working Red Hat system, you can install Gentoo on another partition or drive. In this case, no installation CD is necessary at all. Of course the data has to come from somewhere and if you don’t have it on a CD, it must come from a network (or filesystem, etc).

The Gentoo installation CD is basically a fancy boot disk optimized by including all the handy tools you could possibly want to have access to while you handcraft your operating system. The emphasis of this CD is booting a working Linux system that has tons of handy tools and, just as importantly, a working network connection, if possible. Usually, the boot disk will auto-detect your NIC hardware and automatically use DHCP and be ready for action without doing anything. If your installation is more difficult, oh well, at least you have the full power of Linux and its tools to dig yourself out of that hole.

I find that the rescue disk known as sysresccd is a great tool for all kinds of Linux jobs. I always like to have one lying around. Even better if your system can boot it is a sysresccd USB key. This disk has been very effective for me as a substitute for the real Gentoo install disks. Another trick I would propose that really leverages the power of Gentoo is remote installation. Despite the fact that such a highly customizable distribution needs a lot of customization, you can minimize the impact of this by doing the install completely remotely. If you can log into a computer somewhere (as root), there is a good chance you can do the entire installation procedure from afar. So with the sysresccd or the Gentoo bootdisks, sshd is included and you can fire that up and then go back to your real computer to finish the whole job. If you aren’t following what I’m saying here, don’t worry, it’s just an advanced way to exploit the Gentoo concept.

Xed’s Procedure

Pre Preparation

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

date                # Check the date.
date MMDDhhmmYYYY   # Change if needed.

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

setterm -blank 0

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.

passwd
/etc/init.d/sshd start

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.

screen -e^gg   # Where ctrl-g is my favorite escape key.

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.

Drive/Media Preparation

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.

fdisk /dev/sda

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.

mkfs.ext2 /dev/sda1

Format the main drive or drives.

mkfs.ext3 /dev/sda2

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.

mkswap /dev/sda4

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?

swapon /dev/sda4

Mount Target Drive

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

mount -t ext3 /dev/sda2 /mnt/gentoo

Extract Gentoo

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:

SITE=ftp.gtlib.gatech.edu
FILE=/pub/gentoo/releases/amd64/autobuilds/current-stage3-amd64/stage3-amd64-20160317.tar.bz2
wget ${SITE}/${FILE}
lftp -e 'get ${FILE} ; quit' ${SITE}

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:

wget ${SITE}/${FILE}.DIGESTS
cat stage3-x86-2006.0.tar.bz2.DIGESTS
md5sum stage3-x86-2006.0.tar.bz2           # Do they look the same?

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.

time tar -xjpf /mnt/cdrom/stages/stage3-i686-2004.3.tar.bz2 -C /mnt/gentoo

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

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

S=${SITE}/${FILE}
# Another good mirror: ftp://ftp.ucsb.edu/pub/mirrors/linux/gentoo/
wget -O - $S | tar -xjf - -C /mnt/gentoo # Install directly.
wget -O - $S | ssh target.machine.com tar -xjf - -C /mnt/gentoo # Push from a relay.

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

Note
I used to use x86, but when I was compiling for a modern system (2013) I got to compiling the kernel and ran into an error. I realized that the x86 tree from the repositories produces a 32 bit distribution. This is clearly obsolete for any new hardware. The answer was to do something like shown in the example above with the amd64 path. Use something like file /mnt/gentoo/sbin/init to check to see if the distribution you’re using is what you want.

Mount Other Systems

Assuming there is a boot partition.

mount -t ext2 /dev/sda1 /mnt/gentoo/boot

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.

mount -t proc none /mnt/gentoo/proc
mount --rbind /dev /mnt/gentoo/dev
mount --make-rslave /mnt/gentoo/dev
mount --rbind /sys /mnt/gentoo/sys
mount --make-rslave /mnt/gentoo/sys

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

Borrow DNS Settings

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.

cp -L /etc/resolv.conf /mnt/gentoo/etc
chmod 644 /mnt/gentoo/etc/resolv.conf

make.conf

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.

scp xed@$XED:/etc/portage/make.conf /mnt/gentoo/etc/portage/

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

/mnt/gentoo/usr/share/portage/config/make.conf.example

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

CHOST="x86_64-pc-linux-gnu"

Note that a good CFLAGS value is something like this.

CFLAGS="-march=native -O2 -pipe"

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.

cat /proc/cpuinfo
gcc -march=native -E -v - </dev/null 2>&1 | grep cc1

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

Some important /proc/cpu "flags":

  • lm: "Long Mode". Supports the AMD64 instruction set. This means your CPU is definitely not constrained to only running 32-bit software.

  • vmx: Intel Vanderpool hardware virtualization technology

  • svm: AMD Pacifica hardware virtualization technology

  • tm: "Thermal Monitor". Thermal throttling with IDLE instructions. Usually hardware controlled in response to CPU temperature.

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

# == USE Flags
# For available list, see: `less /usr/portage/profiles/use.desc`
USE=""
USE="${USE} -directfb -gpm -cjk -gnome -kde -cups -pulseaudio "
USE="${USE} -gtk -alsa -X -bluetooth"
USE="${USE} bzip2 lzo unicode sse "
USE="${USE} aalib imap network sasl gnutls "

# == Host Setting
CHOST="x86_64-pc-linux-gnu"

# == Host and optimization settings
CFLAGS="-march=native -O2 -pipe"
CXXFLAGS="${CFLAGS}"
FFLAGS="${CFLAGS}"
FCFLAGS="${FFLAGS}"

ACCEPT_KEYWORDS="~amd64"
ACCEPT_LICENSE="-* @FREE"

# == Portage Directories
PORTAGE_TMPDIR=/var/tmp
PORTDIR=/usr/portage
DISTDIR=/usr/portage/distfiles
PKGDIR=/usr/portage/packages
#PORT_LOGDIR=""
#PORTDIR_OVERLAY=/usr/local/portage

PORTAGE_NICENESS=3
PORTAGE_IONICE_COMMAND="ionice -c 3 -p \${PID}"
AUTOCLEAN="yes"

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

/etc/portage/repos.conf
[gentoo]
sync-type = rsync
sync-uri = rsync://mirror.example.edu/gentoo-portage

Specify Drives In fstab

Set mountpoints for your drives.

vim /mnt/gentoo/etc/fstab

Something like this is typical:

/dev/sda2               /               ext4            noatime 0 1
/dev/sda3               /data           xfs             noatime 0 0
/dev/sda4               none            swap            sw 0 0
/dev/sdd1               /mnt/usbmem     vfat            noauto 0 0
/dev/cdroms/cdrom0      /mnt/cdrom      iso9660         noauto,ro 0 0
proc                    /proc           proc            defaults 0 0
shm                     /dev/shm        tmpfs   nodev,nosuid,noexec 0 0

Change Filesystem Root

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

chroot /mnt/gentoo /bin/bash

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.

Set Time Zone

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

date
date MMDDhhmmYYYY.ss
# The first may be obsolete and replaced with the second:
ln -sf /usr/share/zoneinfo/America/Los_Angeles /etc/localtime
echo America/Los_Angeles > /etc/timezone

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

Proxy

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

PROXY=webproxy.EXAMPLE.edu:3128
export ftp_proxy=${PROXY}
export http_proxy=${PROXY}
export https_proxy=${PROXY}

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

env-update; source /etc/profile

Build System

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

ifconfig; ping www.gentoo.org -c3

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.

time emerge-webrsync
time emerge --sync

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.

time emerge --oneshot portage

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

Profile

Get the profile properly selected.

eselect profile list
eselect profile set 2    # <-- Only if not satisfactory.
eselect locale list

System

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

time emerge -v system

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.

Install Stuff

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:

emerge app-editors/vim --pretend --verbose
emerge vim -pv # You don't really need the category unless there's a clash.
# Maybe make some adjustments here to "USE=" in /etc/portage/make.conf
time emerge vim
emerge tree pinfo lsof atop -av # You can install many at once.

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:

USE="-gnome kde" emerge ethereal
USE="-X" emerge -av vim
USE="tcltk" emerge python

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:

emerge -s john # Which finds package: johntheripper

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.

Packages I Like

Actually, some of these packages I merely tolerate.

Gentoo Specific System Managment

  • sys-devel/bc - REQUIRED FOR LINUX KERNEL COMPILING

  • app-portage/gentoolkit (contains the essential revdep-rebuild, glsa-check)

  • app-portage/ufed

  • sys-kernel/gentoo-sources

  • sys-kernel/genkernel

Serious User Tools

  • sys-fs/mdadm

  • sys-apps/lm_sensors

  • sys-apps/pciutils (lspci)

  • app-editors/vim

  • app-misc/screen - Use --exclude screen in @world updates run inside screen to prevent reattachment problems.

  • mail-client/mutt

  • net-ftp/lftp

  • sys-apps/less

Deluxe Commands

  • app-text/tree

  • app-text/pinfo

  • sys-process/lsof

  • sys-process/htop

  • sys-apps/dmidecode

  • sys-apps/util-linux (ionice, lsblk, etc)

System Management

  • sys-boot/grub:2

  • net-misc/dhcpcd

  • net-firewall/iptables

  • sys-apps/eject

  • sys-apps/pciutils

  • sys-apps/usbutils

  • sys-apps/smartmontools

System Services

  • net-misc/openssh

  • app-text/rcs

  • dev-util/cvs

  • net-fs/nfs-utils

  • app-admin/metalog

  • mail-mta/ssmtp (Very simple forwarding MTA)

  • sys-process/vixie-cron or maybe try sys-process/cronie

  • sys-process/at

  • net-misc/ntp

  • net-www/apache

Documents

  • app-text/asciidoc

  • app-text/tetex

  • app-text/antiword

Systems and Networking

  • net-misc/whois

  • net-analyzer/iptraf-ng

  • net-analyzer/hping

  • net-analyzer/tcpdump

  • net-analyzer/nmap

  • net-dns/bind-tools

  • net-analyzer/traceroute

  • net-analyzer/netcat

  • net-analyzer/wireshark

  • app-crypt/johntheripper

  • app-admin/tripwire

  • sys-fs/sshfs-fuse

Database

  • dev-db/pygresql

  • dev-python/sqlobject

  • dev-db/pgadmin3

  • dev-db/mysql

  • dev-python/mysql-python

File Management

  • app-arch/gzip

  • app-arch/zip

  • app-crypt/gnupg

  • app-crypt/ccrypt

Internet Utilities

  • www-client/links

  • www-client/lynx

  • www-client/mozilla-firefox

  • net-im/centericq

Languages

  • dev-java/blackdown-jdk

  • dev-java/blackdown-jre

  • dev-lang/tcl

  • dev-python/ipython

  • app-text/ghostscript-esp NEEDS X

  • app-text/a2ps NEEDS ghostscript-esp, X

Graphics

  • x11-base/xorg-x11 (maybe xorg-server is better for minimal, less fonts)

  • x11-drivers/xf86-input-evdev (If this doesn’t come along automatically, needed for input)

  • x11-terms/aterm (definitely this or xterm, some kind of terminal - fix /etc/X11/xinit/xinitrc)

  • x11-wm/ratpoison

  • x11-wm/blackbox

  • x11-misc/bbkeys

  • media-gfx/xv

  • media-gfx/inkscape

  • media-gfx/gimp

  • app-text/xpdf

  • app-text/gv

  • sci-visualization/gnuplot

  • www-client/mozilla-firefox

  • media-gfx/imagemagick

  • media-video/mplayer

  • media-gfx/gphoto2

  • media-gfx/jhead

Noises

  • media-sound/alsa-utils

  • media-sound/alsa-tools

  • app-cdr/cdrtools

  • media-sound/sox

  • media-sound/mpg123

  • media-sound/alsaplayer

  • media-sound/abcde

  • media-sound/mp3blaster

Fonts

  • media-fonts/*

arkpandora artwiz-aleczapka-en cheapskatefonts corefonts dejavu font-adobe-100dpi font-adobe-75dpi font-adobe-utopia-100dpi font-adobe-utopia-75dpi font-adobe-utopia-type1 font-alias font-bh-100dpi font-bh-75dpi font-bh-lucidatypewriter-100dpi font-bh-lucidatypewriter-75dpi font-bh-ttf font-bh-type1 font-bitstream-100dpi font-bitstream-75dpi font-bitstream-speedo font-bitstream-type1 font-cursor-misc font-misc-misc font-dec-misc font-ibm-type1 font-micro-misc font-schumacher-misc font-sony-misc font-sun-misc font-util font-xfree86-type1 freefont-ttf freefonts gnu-gs-fonts-other gnu-gs-fonts-std lfpfonts-fix lfpfonts-var liberation-fonts-ttf terminus-font ttf-bitstream-vera urw-fonts

Basic Kernel Compiling

Kernel Resources

Summary of Creating A Kernel

Gentoo has something called genkernel which is supposed to help deal with kernel issues in some way. I find that it’s just better to avoid this.

If you know what you’re doing, you probably should just go to kernel.org and get your own kernel source. This is actually the recommended way I do things now. I don’t really get too much help from the Gentoo kernel source package which has just enough hand holding to be dangerous. Something like this will create an up to date kernel source tree:

time wget -qO- https://www.kernel.org/pub/linux/kernel/v3.x/linux-3.10.14.tar.xz | tar -xvJf - -C /mnt/gentoo/usr/src/

Compiling the kernel generally involves the following steps.

  1. Edit the .config file.

    • make oldconfig - use an existing .config as a template and adjust to it.

    • make menuconfig - ncurses menu of all options.

    • make xconfig - Graphical menu. This is nice because it shows the help for each item automatically.

  2. make

  3. make modules

  4. make modules_install

  5. make install - Installs System.map-x.y.zz, config-x.y.zz, vmlinux-x.y.zz in /boot.

  6. Optional: If you think there is no alternative to using an initialization ram image at boot (initrd or initramfs.img) you may wan to explore the Dracut system which can build such a thing. This being a notable annoyance, it is often better with custom compiled kernels to simply compile exactly what you need for that computer to boot.

Tips

  • Don’t forget the very useful make help.

  • I noticed that the kernel compile process can require bc; this means you will at some point probably need emerge sys-devel/bc.

Kernel Options

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

  • Everything the system needs to boot or everything your system needs to use all its hardware if modules are not used. For booting focus on the boot drive’s hardware being supported.

  • All file systems you will want to mount.

  • Languages you think the kernel should know about.

  • As many hardware optimizations your hardware can take advantage of as possible. Why not?

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

<ALT-F2> dmesg | less; <ALT-F3> lspci

Specify Services To Run At Boot

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.

SERVS="sshd vixie-cron net apache2 alsasound atd metalog net.eth0 ntpd"
for X in $SERVS; do rc-update add $X default; done

Set The Right Editor

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:

eselect editor set vim
emerge --unmerge nano

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.

/etc/env.d/99editor
# Configuration file for eselect
# This file has been automatically generated.
EDITOR="/usr/bin/vim"

Install Bootloader - Grub2 - The New Way

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

Note
It might be necessary to set the device-mapper USE flag for systems where GRUB will need to detect RAID.

Basically it’s like this:

emerge --ask sys-boot/grub:2
mount /boot # If it's not already mounted.
mount -o remount,rw /boot # Only if having read-only problems
grub2-install /dev/sda
grub2-install /dev/sdb # Only if you're doing a RAID1 setup
chmod -x /etc/grub.d/[234]*
grub2-mkconfig -o /boot/grub/grub.cfg

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:

/boot/grub/grub.cfg
timeout=5

menuentry 'Gentoo Linux 3.2.12' {
    root=hd0,1
    linux /boot/kernel-3.2.12-gentoo root=/dev/sda3
}

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:

rsync -aP /mnt/a_boot/ /mnt/b_boot/

Install Bootloader - Grub1 - The Old Way

vim /boot/grub/grub.conf

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

Install the bootloader using the grub shell.

# grub --no-floppy
 grub> root (hd0,0)
 grub> setup (hd0)
 grub> quit

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

grub-install --no-floppy /dev/sda

Set Password

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

passwd

Set Locales

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

Set Up Networking

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.

vi /etc/resolv.conf
vi /etc/conf.d/hostname # hostname="www.example.edu"
vi /etc/conf.d/net
cd /etc/init.d
ln -s net.lo net.eth0
rc-update add net.eth0 default
Note
The device eth0 can not be taken for granted as modern systems love to name the ethernet devices in the most Baroque way possible. Check the results for ifconfig -a to see what your kernel thinks the device is. What’s really fun is when the boot disk your using and the system you’re installing differ.

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

bunzip2 -cd /usr/share/doc/netifrc-*/net.example.bz2 >> /etc/conf.d/net

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:

# Chris' most simple static IP net.conf
config_eth0="123.111.243.112 netmask 255.255.255.224"
routes_eth0="default via 123.111.243.97"
dns_servers_eth0="132.239.99.252"
Here’s another one that has worked more recently:
config_enp2s0="123.111.110.243.115/27"
routes_enp2s0="default via 123.111.110.243.97"
dns_servers_enp2s0="132.239.99.252"
dns_domain_enp2s0="example.edu"
Note
The "dns_domain" entry seems to do nothing at all.

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.

123.111.243.115 myhost.example.edu myhost

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.

Reboot

Get out of the chroot situation.

exit; cd /

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

umount /mnt/gentoo/proc /mnt/gentoo/boot /mnt/gentoo

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.

reboot

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.

SSH Server

Since Gentoo can take a long while to install properly, it’s often nice to be able to do most of the install work from another machine. In fact, it’s a nice feature to be able to sit at your most comfortable workstation and work on installing Gentoo on some machine with a bad keyboard/display in a freezing cold server room. The trick is to set up a ssh daemon.

When starting sshd from sysresccd and other miscellaneous boot/rescue disks, you might need to explicitly set up the keys.

for TYPE in "rsa dsa rsa1"; do ssh-keygen -t $TYPE -f /etc/ssh/ssh_host_$TYPE_key; done

There might be an easier way to do this. With real Gentoo install disks, and maybe others, it’s all automatic with:

/etc/init.d/sshd start

Run the ssh server. Don’t forget to set a known password!

sshd
passwd
ssh localhost  # Test. Then Ctrl-d.

Test that connections are being accepted. A better test is to log in to the machine you want to work from and see if you can log back into the install machine.

Locked out of SSH after an update? Ya, it happens! Here is a bug that discusses the issue that caught me (see comment #16 for a hint on how to fix it). But the general message is to test your SSH after updating OpenSSH before you log out (if working remotely).

Network Time Protocol - Getting Correct Time

An accurate clock ranges from nice to critically essential. Gentoo has made some changes in the way ntp is used. Basically ntpd has taken over the job of ntp-client. These days, setting up ntp is not very problematic.

Get the ntp software including ntpd and utilities.

emerge ntp

Add NTPCLIENT_OPTS. I use ntp.ucsd.edu (132.239.1.6). This is probably only necessary if you want to get fussy about which time server you use. You’ve made it this far with Gentoo - of course you’re fussy!

vim /etc/ntp.conf
vim /etc/conf.d/ntpd
vim /etc/conf.d/ntp-client # Is this still valid?

Start the client now.

/etc/init.d/ntp-client start

Set ntp to run at boot. Repeat this process for ntpd.

rc-update add ntpd default

lm_sensors

emerge -avuD sys-apps/lm_sensors
/usr/sbin/sensors-detect # Set up /etc/conf.d/lm_sensors

Correcting The Error Of The Caplock Key

Upgrading To A New "Profile"

At anytime you can update your system so that it is taking advantage of the latest stable versions of everything you use. That is a Gentoo perk. Every once in a while Gentoo comes out with a new "profile", for example, 2004.3 changes to 2005.1, etc. What exactly this means is more subtle than with distributions that use distribution numbers to imply a set of programs frozen at some particular version. A Gentoo profile tends to affect the default way things are organized and things like which version of portage is recommended. The practical effects of a new profile are often not all that serious, however, it’s a nice idea to update when you can. Fortunately it’s very easy.

This symlink is how the current profile for the system is defined. If you want your system to behave like another version, this is where you set that.

ln --no-dereference -sf ../usr/portage/profiles/default-linux/x86/2005.1 /etc/make.profile
emerge --sync   # Sync the portage database.
emerge portage  # Update portage if needed.
emerge -uD world

Update everything. The -u is update, the -D is look deep into dependencies, and world is all of the stuff you have currently installed. You might want to do a -pv to preview the changes that will be made and see if you have a problem with anything. Also, previewing will give you an idea of how long the update might take. It can take quite a while.

After the upgrade, you can update any configuration files that may have been affected. This is probably a good idea. This allows you to incorporate new config files for various reinstalled items. This can be critically necessary to make new versions work, but it can also wipe out things that you’ve customized (like a web server config file, for example). So follow instructions and watch what you’re doing.

etc-update

There’s a reason why Richard Stallman calls them Nvidious. If you use an Nvidia graphics card, better run your special driver installer again. If you don’t or don’t care about 3d, don’t worry about it.

sh NVIDIA.....

Troubleshooting and Update Tips

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.

Known Gentoo Repair Techniques
perl-cleaner --all
perl-cleaner --reallyall
python-updater
eselect python list
eselect help
gcc-config -l
binutils-config -l
emerge --depclean
revdep-rebuild  (emerge -avuD gentoolkit)
emerge @preserved-rebuild
fix_libtool_files.sh
etc-update
env-update
eselect news read new | less
emerge --backtrack=30 --vebose-conflicts <package>
wgetpaste -t -s dpaste -c "emerge --verbose-conflicts --backtrack=100 -avuD portage"
MAKEOPTS="-j1" emerge .....

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.

How Ebuilds Are Named - Details

Full details are found in man 5 ebuild. Let’s say you have this ebuild.

sys-libs/ncurses-6.0-r1:0/6::gentoo

Or, structurally, something like this.

=category/package-version[use flags maybe]:slot/subslot::repository

Let’s break this form into: "C/P-Vv:S/s::c"

  • C - Category, the directory in /usr/portage/ where the ebuild lives.

  • P - Package name.

  • V - Major version number.

  • v - _alpha, _beta, _pre (pre-release), _rc (release candidate)

  • S - Main slot, used mostly for co-installability. Official slot help.

  • s - Subslot, denotes some kind of ABI.

  • c - Repository Constraints, search man portage for ::.

Multiple Package Instances Within A Single Package Slot

Don’t you just hate it when this happens?

!! Multiple package instances within a single package slot have been pulled
!!! into the dependency graph, resulting in a slot conflict

Often totally mysterious. I have cured this problem with revdep-rebuild, but I have also seen this problem where that was not the cure. Here is an excellent article about possible helpful strategies.

Perl Problems

Very often (it seems) I get a failure in something technical and complex which turns out on closer examination to be related to a Perl problem. I was hoping to stop thinking about Perl in about 2005 but it’s still important. Here is an example of a failure where emerging sys-boot/grub-2.00 causes a cryptic show stopping error.

* ERROR: sys-boot/grub-2.00_p5107-r2::gentoo failed (compile phase):
*   emake failed

Now you wouldn’t jump to a conclusion that this had anything to do with Perl whatsoever. But look closer.

config.status: creating grub-set-default
Can't locate Locale/gettext.pm in @INC (@INC contains: /etc/perl /usr/local/lib/perl5/5.16.3/i686-linux /usr/local/lib/perl5/5.16.3 /usr/lib/perl5/vendor_perl/5.16.3/i686-linux /usr/lib/perl5/vendor_perl/5.16.3 /usr/local/lib/perl5 /usr/lib/perl5/vendor_perl /usr/lib/perl5/5.16.3/i686-linux /usr/lib/perl5/5.16.3 .) at /usr/bin/help2man line 28.
BEGIN failed--compilation aborted at /usr/bin/help2man line 28.

If you didn’t know that .pm meant "Perl module" this could be very tricky to figure out. Noticing the Perl library include path (@INC) can be easy to miss too if it’s buried in a ton of other gobbledygook.

The solution is to run sudo perl-cleaner --reallyall. The first time I ran this for the problem shown, it crashed on a certain package which I re-emerged with sudo emerge -1v virtual/perl-digest-base. Then back to sudo perl-cleaner --reallyall again which finally completed successfully. Once that was done the original emerge was started again. Again, the exact same place crashed. Again the perl-cleaner was run. Then finally, the original emerge was able to continue.

Ok, let’s say that perl-cleaner as described also doesn’t work. It happens! Sometimes perl-cleaner dies with this very helpful message.

 * If you encounter blockers involving virtuals and perl-core, here are
 * some things to try:
 *   Remove all perl-core packages from your world file
 *     emerge --deselect --ask $(qlist -IC 'perl-core/*')
 *   Update all the installed Perl virtuals
 *     emerge -uD1a $(qlist -IC 'virtual/perl-*')
 *   Afterwards re-run perl-cleaner

Of course often after you do part one, you’ve lost the syntax for part two. Hence its appearance here. If you don’t use that second command, you can be in for tons of individually removing Perl packages in order to clear the way for new ones.

Kernel Problems

Make sure your kernel options are adequate.

  • CONFIG_DEVTMPFS=y

  • CONFIG_FHANDLE=y

  • CONFIG_NET=y

  • CONFIG_SYSVIPC=y

  • CONFIG_BLK_DEV_BSG=y

Apparently these ones should not be set.

  • CONFIG_IDE=n

  • CONFIG_SYSFS_DEPRECATED=n

Here’s a helpful message for when your kernel is hiding from Gentoo:

 * Messages for package sys-fs/udev-216:

 * Unable to find kernel sources at /usr/src/linux
 * Unable to calculate Linux Kernel version for build, attempting to use running version
 * Unable to check for the following kernel config options due
 * to absence of any configured kernel sources or compiled
 * config:
 *  - BLK_DEV_BSG
 *  - DEVTMPFS
 *  - !IDE
 *  - INOTIFY_USER
 *  - !SYSFS_DEPRECATED
 *  - !SYSFS_DEPRECATED_V2
 *  - SIGNALFD
 *  - EPOLL
 *  - FHANDLE
 *  - NET

I’m going to take this to suggest that for Gentoo it’s probably good to include the IKCONFIG option under "General setup" so that /proc/config.gz is present.

Do you have sys-devel/bc installed? If you’re compiling a kernel, that might become necessary.

GCC Problems

GCC problems are common because this is a very tricky piece of the puzzle. If you’re dealing with a lot of machines and can get away with it, it’s best to compile GCC once and make binary packages for other machines to save the trouble. This is also perhaps true fro glibc too. Each of these can take hours to compile as well as inordinate RAM and hard drive resources. See the binary packages section for details.

Don’t mess up your GCC. If you do, maybe this will help recover it. Basically, you need to do this when upgrading GCC.

emerge -u gcc
gcc-config -l
gcc-config 3   # Pick the latest one generally
env-update && source /etc/profile
emerge --oneshot libtool
revdep-rebuild --library libstdc++.so.5
gcc --version
emerge -C =sys-devel/gcc-3.3.3  # Uninstall the old one.
MAKEOPTS="-j1" # Maybe helps struggling compile processes (e.g. boost)

Seriously, make sure you do the gcc-config 3. I had a situation where nothing would progress until I did a gcc-config -l and saw there was only one gcc. I then did a cgg-config 1 and it all started working again. So this can be pretty important.

If you’re still having gcc problems, consider recompiling sys-libs/glibc. Then have a go at the gcc again. I have found this to be the answer on two diverse machines.

On the other hand, sometimes you try to emerge gcc and it tries to compile a new glibc and fails because it says you need a new compiler. Duh! To cure that just emerge -1 gcc:4.8. Use the version recommended of course.

See the following for gcc’s memory liability.

On the other hand, if you have way more memory than disk space (which isn’t XFS over NFS), consider using RAM for the portage disk cache like this.

mount -t tmpfs gcctemp /var/tmp/portage

Related to gcc issues is sys-devel/binutils. I’ve had this fail now several times. The cure so far has been to examine my compile flags carefully. For example, recently on an 8 core machine I had -j9 which was mostly reasonable. But I lowered it to -j1 and my mystery binutils error vanished.

Memory Issues

Also gcc compiling takes an absurd amount of RAM these days. Make sure you have a swap space. Just make a big file a swap if you need to.

dd if=/dev/zero of=/tmp/tswap bs=1M count=2000
mkswap /tmp/tswap ; swapon /tmp/tswap

Also definitely have MAKEOPTS set to -j1 which should be the default.

I have also run into this exact problem while compiling cmake on a machine with 16GB RAM. That should have been far more than plenty but I was also using no swap space. So sometimes apparently, the swap space is needed just to have it. I wonder if making the swap space 1kB would work? Swap is usually stupid.

Blocks

Very often problems arise because some ancient package blocks the installation of new package somehow. Here’s a completely pathological example.

[blocks B      ] dev-python/pillow ("dev-python/pillow" is blocking dev-python/imaging-1.1.7-r2)
[blocks B      ] dev-python/imaging ("dev-python/imaging" is blocking dev-python/pillow-2.4.0)

Very often the correct thing to do is to simply get rid of the blocking package. However, the caveat is that sometimes, getting rid of the blocking package is disastrous and renders your system completely inoperable or at least unable to continue upgrading. For example, I once got rid of "sys-kernel/linux-headers" and that led to all kinds of grief. To install that package again, it turns out that it, itself, is needed. The answer to such paradoxes is to get the package from a Gentoo which is happily working. One source to consider for such things is tinderbox which is described here.

Sometimes A blocks B and B blocks C and C blocks A. This happens because if A, B, and C were all up to date, they would get along, but the old versions limit each other. This can sometimes be cured with a single emerge that hits all involved packages at once.

emerge -av1 A B C

Any one upgrade in isolation would leave you in invalid state, but performing all the upgrades at once moves from one allowed state to another, without stopping in a disallowed state. I have seen this work and is worth a try.

Of course sometimes even this does not work. For example, on the pillow/imaging problem above, I had to do equery d pillow and equery d imaging until I found everything that depended on them. After finding that one only was required for one thing, I got rid of that thing. This allowed the updates to go properly. Once that was done, add back the thing that caused the trouble.

Python Problems

Python is quite important to Gentoo because, among other things, the Portage system (e.g. emerge) is mostly written in it. When it gets messed up, it can be very challenging to make further progress. Updating and caring for Python installations correctly is essential.

For the complete official story of how this all works see the Gentoo python-r1 User’s Guide. Choosing the default Python interpreters should be done with eselect something like this.

# eselect python list
Available Python interpreters:
  [1]   python2.4
  [2]   python2.5
  [3]   python2.7 *
  [4]   python3.2
  [5]   python3.3
# eselect python show
python2.7
# eselect python list --python3
Available Python 3 interpreters:
  [1]   python3.2 *
  [2]   python3.3
# eselect python set --python3 python3.3
# eselect python list --python3
Available Python 3 interpreters:
  [1]   python3.2
  [2]   python3.3 *
# python-updater

Actually I’m told that now there is no star by the selected one and that the one that’s active is just the first one. Which is very confusing.

Or to change to the latest (v3?) Python.

eselect python set 2

Where "2" is the number (not Python version) of the Python you want as listed by eselect python list.

A new thing I’ve run into is some USE flag complaining which can sometimes be resolved by adding something like the following to a /etc/portage/make.conf file.

USE_PYTHON="2.7 3.3"
PYTHON_TARGETS="python2_7 python3_3"
PYTHON_SINGLE_TARGETS="python2_7"

wraeth adds that putting something like python_targets_python3_6 in your USE variable can be helpful. And I think that’s what the USE_PYTHON is sort of doing.

Just adding that cured a lot of complaining about Python USE flags. Of course python is in the USE flags but other than that, nothing else had to be done with them.

I had a bunch of trouble like this and finally was able to cure it by getting rid of some old Python versions. iamben certified that if you have 2.7 working and 3.4 available, this should be kosher.

sudo emerge -aC python:3.3 python:3.2

That unblocked all kinds of things.

Find interesting problems and anomalies with:

  • Check grep -ri python_targets /etc/portage.

  • Check grep python /var/lib/portage/world.

Don’t forget to run python-updater at the end. Hang on… looks like python-updater is no longer needed/advised/available. Ignore that.

Security Problems

Security Problems? Find out.

/usr/bin/glsa-check -l -nc 2>/dev/null | /bin/fgrep "[N]"

This program lives in gentoolkit which is pretty much not optional for a happy Gentoo.

Configuration Files

Often updates and bug fixes take the form of changes in the supplied configuration files. For example, when ntp was found to be helping DoS attacks, the solution was just to configure correctly operating program differently. The main classic way to update these files is with etc-update. I find this interface to be really annoying for some things. Mainly when you’ve spent huge amounts of time getting your mail or web server to work and it casually comes in and wants to destroy that in an instant because of some change in comments, that is unnerving. My procedure is to do the following.

  • Run etc-update to get a list of changes that are pending. Quit immediately without doing anything.

  • For scan the list for any configurations you really care about (hint: if you know about them, you probably care).

  • Manually fix each of the sensitive ones using vimdiff.

    vimdiff /etc/ntpd.conf /etc/._cfg0000_ntpd.conf

    Simply compare the two lines next to each other and use Ctrl-W followed by "h" or "l" (normal Vi keys) to jump back and forth from the old on the left to the suggested new on the right. Use "Y" and "p" to yank and put entire lines from the one you want to the one to update. * Save the corrected original. Delete the proposed new one (._cfg0000_). * Re-run etc-update when only the files you don’t care about are left. Use -5 to automatically accept all of the up dates.

This technique will highlight the things you did to your files and allows good explicit control with and easy to implement interface.

Note that you can set vimdiff to always show differences when using etc-update. Just make sure this is the active diff command here.

/etc/etc-update.conf
diff_command="vim -d %file1 %file2"
using_editor=1

Problems With Emerge

Sometimes when you do an emerge it complains that something is "blocked" by something else. This means that by installing whatever it is you want to install, you will clobber or otherwise conflict with something already in place. Often this happens indirectly with system related dependencies that you have very little understanding of. The general solution is to delete the blocking package and try again. The way you delete is by using emerge --unmerge. Here’s an example that happened when the basic organization of how authentication was changed:

# emerge -uD world -av  # Note that "shadow" is blocked.
!!! Error: the sys-apps/pam-login package conflicts with another package;
# emerge --unmerge sys-apps/pam-login
# emerge shadow -av     # Put this facility back right now.
# emerge -uD world -av  # Continue. Should be good.

Some other things to keep in mind are revdep-rebuild. This command should be run early and often because it helps sort out all kinds of issues with library dependencies. Another thing to check out is python-updater. This can cure irritating problems involving Python or Portage itself (implemented in Python). Seems like revdep-rebuild is no longer needed.

This has been providing excellent results lately for obnoxious blocks on updates that have not kept up as punctually as they should.

emerge --backtrack=100 --verbose-conflicts -avuDN @world

Clearing Disk Space

One problem with installing things that can happen after you’ve used your system a while is that the drive becomes full. Here are some good places to start to look to free some of that:

  • Get rid of everything here: /var/tmp/portage/*

  • Try: eclean-dist -i and eclean-pkg

  • Remove packages! List installed packages by size: qsize -a -k | sort -n -k 6 The good way to get rid of stuff is to run this first and see what collateral damage it would do: emerge -pv --depclean win32codecs. You can also do qdepends -a win32codecs to see what depends on a suspected useless package. Actually, looks like equery d atom is the better plan for dependencies.

  • Remove old kernel sources in /usr/src

  • If you normally have hundreds of megabytes and that’s plenty for normal work, but emerge compiling causes temporary cruft that fills your drive, you can offload that to a separate drive by adding something like this to your /etc/portage/make.conf:

    PORTAGE_TMPDIR=/usbdisk/var_tmp_portage

USE Flags

Want to have a look at your USE flag options? Try this:

cat /usr/portage/profiles/use.* | less

Or if you’re really serious about USE flags, Gentoo has a very compact utility to understand and edit them.

emerge ufed
ufed

Some USE flags I like to consider:

  • imap - Especially helpful with mutt.

  • svg - Scalable Vector Graphics, generally a "Good Thing".

  • opengl - If you want graphics, you might want 3d graphics

  • -X - For text only machines.

  • -bluetooth - Come on. That’s crazy.

  • alsa -oss - Try to convince software to do sound the advanced Linux way.

  • ogg - The righteous codec.

  • verbose - As if the build process didn’t output enough junk.

  • x86 - For normal machines.

  • amd64 - For fancy machines (other fancy machines are available).

  • ldap - For use on fancy systems run by fancy admins.

  • sse sse2 - Floating point optimizations (see /proc/cpuinfo)

  • nvidia - For Nvidious displays.

  • -git - WTF is package gettext pulling in git for? It’s huge!

New for 2015! For x86 and amd64 systems the USE flags corresponding to the instruction sets and other features specific to the x86 (amd64) architecture are being moved into a separate USE flag group called CPU_FLAGS_X86. So what was this…

USE="mmx mmxext sse sse2 sse3"

Becomes…

CPU_FLAGS_X86="mmx mmxext sse sse2 sse3"

Most of the flag names match /proc/cpuinfo names, with the notable exception of SSE3 which is called pni in /proc/cpuinfo (please also do not confuse it with distinct SSSE3).

There is a tool that helps with this.

$ emerge -1v app-portage/cpuid2cpuflags
$ cpuinfo2cpuflags-x86 >> /etc/portage/make.conf

Cron

Historically I have always used sys-process/vixie-cron. I felt like this was the classic. But for about 10 years now I’ve had this bug where changes made to the crontab do not take effect until /etc/init.d/vixie-cron restart is done. Other than that, it works fine and I’m happy with it.

The Gentoo Handbook seems to favor sys-process/cronie which might be worth trying. Apparently it uses inotify and is quite functional.

Apparently if you emerge virtual/cron you will get Gentoo’s default cron implementation. Might be the thing to do.

Mail Configuration

USE='imap' emerge mutt
# vi ~/.muttrc
    set sendmail="/usr/sbin/ssmtp"
# vi /etc/ssmtp/ssmtp.conf
    mailhub=smtp.west.cox.net
    rewriteDomain=xed.ch

Or if the machine only needs to get status messages (bad RAID, overheating, logwatch, etc) consider mail-mta/nullmailer. Some reasonable information about it can be found here.

And maybe mail-client/mailx for command line mailings (from cron jobs, for example).

Web Server

emerge -avuD www-servers/apache
# vi /etc/apache2/httpd.conf
    Listen 8000  # <- Change port (to get around ISP's "service")
    ServerAdmin webmaster@correctemail.ch
# vi /etc/conf.d/apache2
    APACHE2_OPTS="-D USERDIR"
# vi /etc/apache2/vhosts.d/default_vhost.include
    DocumentRoot "/var/www/localhost/xedshtdocs"
    Directory "/var/www/localhost/xedshtdocs"
# rc-update add apache2 default
# /etc/init.d/apache2 [start|restart]

Display & Window Manager

# emerge xorg-server bbconf bbkeys bbdate
# emerge x11-drivers/xf86-input-evdev
# env-update; source /etc/profile
# Generate a /etc/X11/xorg.conf file.
# Xorg -configure
# mv /root/xorg.conf.new /etc/X11/xorg.conf
-- Proview 766s 1280x1024 (75Hz|,80kHz-)
-- 3Dfx Banshee 16384kb Ram
# emerge blackbox; emerge bbkeys

Sound

emerge alsa-lib alsa-utils mpg123
rc-update add alsasound boot # This does important things
alsamixer # unmute what you need and set your levels
alsactl store # Save current mixer settings
/etc/init.d/alsasound start # Start it now too.

Enabling users to use the su command and sound. Add user xed to wheel and audio group:

gpasswd -a xed wheel audio

Or just edit the group file:

wheel::10:root,xed
audio::18:xed

Software Suspend

Enable swsusp under power management in menuconfig.

emerge hibernate-script

Package Management

How can you figure out what package is responsible for a certain file on your system?

equery b /path/to/file_of_interest

How can you tell what use flags a currently installed and functioning package was compiled with?

equery u package-of/interest

Fancy Gentoo Stuff

Binary Packages

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.

Preparation For Binary Packages

The first place to look when exploring binary packages is the following.

$ grep PORTDIR /etc/portage/make.conf
PORTDIR="/usr/portage"
DISTDIR="${PORTDIR}/distfiles"
PKGDIR="${PORTDIR}/packages"

The distfiles is where packages get downloaded before they get compiled (often safe to clear this out to save space) and the packages is a directory you will need if you want to build and use binary packages.

Creating Binary Packages

There are a couple of ways to make binary packages. You can specify that you want binary packages made when you emerge the packages in the first place (see --buildpkg option). However, because you can’t be certain that the emerge will be successful, I prefer two explicit steps; this requires quickpkg.

$ emerge -avuD sys-devel/binutils sys-libs/glibc sys-devel/gcc
$ quickpkg sys-devel/binutils sys-libs/glibc sys-devel/gcc
$ ls /usr/portage/packages/*/*
/usr/portage/packages/sys-devel/gcc-4.9.3.tbz2
/usr/portage/packages/sys-libs/glibc-2.21-r1.tbz2

Using Binary Packages

Copy them to the host they’ll be used on (same directory). Or export them or make them available over HTTP. Lots of options really. Assuming the binary packages are present on the machine which needs them, emerge with --usepkg. Or --usepkgonly which fails if a binary package can’t be used.

$ emerge --usepkgonly sys-libs/glibc sys-devel/gcc

USE_EXPAND Variables

USE_EXPAND variables, like VIDEO_CARDS et al. allow for this kind of thing to be equivalent.

APACHE2_MODULES="authn_core"
USE="apache2_modules_authn_core"

The USE_EXPAND vars are listed in /usr/portage/profiles/base/make.defaults.

but it is a USE_EXPAND, basically any FOO="" listed in emerge -pv output is and you can always expand FOO="bar" to USE="foo_bar", emerge does this internally

also, in package.use you can do like "www-servers/apache2 APACHE2_MODULES: foo APACHE2_MPMS: bar" if you wanna keep your make.conf cleaner

Colors And Symbols When Emerging

I’ve not found this documented anywhere. iamben hints…

  • green - changing how it was

  • red - enable flag, not changing how it was

  • blue - ?? ignore (this needs to be checked)

There are many cryptic and subtle symbols on the USE flags. See symbols in the --verbose section of man emerge.

  • - - blue - (prefix) means not enabled (either disabled or removed)

  • * - green - (suffix) transition to or from the enabled state

  • % - yellow - (suffix) newly added or removed

  • () - color unknown - circumfix forced, masked, or removed

  • {} - color unknown - circumfix state is bound to FEATURES settings

There are also cryptic symbols on the packages like: [ebuild U *] Also see the OUTPUT section of man emerge.

  • # - package.mask

  • * - missing keyword

  • ~ - unstable keyword

The code letters can be cryptic too. They can be found in the --pretend section of man emerge.

  • N - new (not yet installed)

  • S - new SLOT installation (side-by-side versions)

  • U - updating (to another version)

  • D - downgrading (best version seems lower)

  • r - reinstall (forced for some reason, possibly due to slot or sub-slot)

  • R - replacing (remerging same version)

  • F - fetch restricted (must be manually downloaded)

  • f - fetch restricted (already downloaded)

  • I - interactive (requires user input)

  • B - blocked by another package (unresolved conflict)

  • b - blocked by another package (automatically resolved conflict)

Specifying Custom Repos

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

SYNC="rsync://mirror.ucsd.edu/gentoo-portage"

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

/etc/portage/repos.conf
[gentoo]
sync-type = rsync
sync-uri = rsync://mirror.ucsd.edu/gentoo-portage
Note
This used to work with the section heading being "[DEFAULT]". That stopped working for some reason. I think this is a bit of a moving target right now.