Introduction and Acknowledgements

This is derived from official Gentoo documentation resources (the Gentoo Handbook and especially the Gentoo Linux x86 Quick Install Guide).

Getting a Very Recent Boot DVD/CD

Download a CD or DVD ISO image from my personal mirror ( x86 or amd64 ) or from one of the official Gentoo mirrors. The ISO images are found on the official mirrors in releases/arch/current-iso (that is, for x86, the path would be releases/x86/current-iso).

In any case, this directory also includes the stage3 image(s) for that architecture as well.

Burn the image to a CD or DVD and boot it on the target machine.

This is the most reliable way to get a build environment for Gentoo (in most cases, dummy, remember when you had to build a custom kernel to get to a prompt?). If this doesn't work, then go to the Gentoo Handbook for information and links that will guide you through the more difficult installations.

If the hardware is not going to cause you any problems, you can just press ENTER to boot the frame buffer based Gentoo kernel. If that doesn't work, press F2 at the boot screen to find out what boot options exist. A good second try is to boot to the gentoo-nofb kernel which disables the framebuffer. And if all goes well, the hardware will be detected and the modules will be loaded. If that kernel fails to boot properly or hangs up, you need to read the Gentoo Handbook or Quick Start Guide. In fact, if anything deviates from a perfect install, go look at the documentation! Sorry,...

This Procedure Requires a Network Connection

In most cases the network will be up and running if you have a wired Ethernet connection. Verify this by entering the command ifconfig eth0. Or enter the command ifconfig if that doesn't work. It should report a valid Ethernet IP address (something like 192.168.0.13, for example). If the network is not configured already, use net-setup to configure it. Remember, you might need to load support for a network card using modprobe prior to configuration. And, of course, if this is not enough information, go back to the official documentation.

For wireless access, use iwconfig to set the wireless parameters and then use either net-setup again or run ifconfig, dhcpcd and/or route manually.

If you are behind a proxy, do not forget to initialize your system configuration using

   livecd root # export http_proxy
   livecd root # ftp_proxy
   livecd root # RSYNC_PROXY

Alternatively, start networking manually. The following example assigns the IP address 192.168.1.10 to the new PC and defines 192.168.1.1 as the router and the name server.

   livecd root # ifconfig eth0 192.168.1.10/24
   livecd root # route add default gw 192.168.1.1
   livecd root # echo nameserver 192.168.1.1 > /etc/resolv.conf

Taking Advantage of a Second Computer

Now for us lazy guys who want to scroll back and look at stuff we've forgotten in the last 30 minutes. We can then log into the new system over an ssh link. Then you can work with one of those new-fangled graphics windowing environments.

First, set the root password on the booted minimal or live CD so that we can connect to it from another PC. [Repeating the Gentoo docs advice: please note that allowing root to connect over ssh is not recommended under normal circumstances. If you can't trust your local network, use a long and complex password. I will use it only once as it disappears after the install is complete, that is, on the first reboot.]

Set the root password

livecd root # passwd
New UNIX password: type_a_password
Retype new UNIX password: type_a_password
passwd: password updated successfully
   

Now, start a terminal window on the other PC and connect to the new box, scroll to your hearts content, and cut and paste commands with wild abandon.

Connect to the new box from another PC

(Use the IP address of your new box)
$ ssh root@192.168.1.10
The authenticity of host '192.168.1.10 (192.168.1.10)' can't be established.
RSA key fingerprint is 96:e7:2d:12:ac:9c:b0:94:90:9f:40:89:b0:45:26:8f.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '192.168.1.10' (RSA) to the list of known hosts.
Password: type_the_password

Preparing the Disk for Gentoo

Use fdisk or cfdisk to create your partition layout. You need at least one Linux partition (type 83), and in many cases a second and maybe even a third for /boot and /home. In most cases you will want a swap partition (type 82) as well.

The following scenario creates a /boot, a swap and a main partition as used in our handbook. Replace sda with your disk. Depending on the boot loader (grub, installed in the MBR, for example) the bootable flag may be ignored, but in many cases is is required (grub on GPT disks or any time the boot loader is installed in the partition header). Set this flag on the boot partition with fdisk's a command.

Create the partitions (if needed)

livecd ~ # fdisk /dev/sda

(The rest of this guide uses the following partitioning scheme)
livecd ~ # fdisk -l /dev/sda

Disk /dev/sda: 599.9 GB, 599978409984 bytes
255 heads, 63 sectors/track, 72943 cylinders
Units = cylinders of 16065 * 512 = 8225280 bytes

   Device Boot      Start         End      Blocks   Id  System
/dev/sda1   *           1          12       96358+  83  Linux
/dev/sda2              13         110      787185   82  Linux swap / Solaris
/dev/sda3             111       72943   585031072+  83  Linux

Use mke2fs, mke2fs -j, mkfs.xfs, etc., to create file systems on your Linux partitions. Initialize your swap partition using mkswap and swapon.

Create the file systems and activate the swap

(ext2 is all you need on the /boot partition)
livecd ~ # mke2fs /dev/sda1

(Let's use ext3 on the main partition)
livecd ~ # mke2fs -j /dev/sda3

(Create and activate swap)
livecd ~ # mkswap /dev/sda2 && swapon /dev/sda2

Go Live!

Mount the file systems on /mnt/gentoo. Create directories for the other mount points if you need them (like /mnt/gentoo/boot and /mnt/gentoo/home) and mount them as well.

Mount the file systems

livecd ~ # mount /dev/sda3 /mnt/gentoo
livecd ~ # mkdir /mnt/gentoo/boot
livecd ~ # mount /dev/sda1 /mnt/gentoo/boot
livecd ~ # cd /mnt/gentoo

Now make sure your date and time is set correctly using date MMDDhhmmYYYY. Use UTC time.

Set the date and UTC time

(Check the clock)
livecd gentoo # date
Mon Mar  6 00:14:13 UTC 2006

(Set the current date and time if required)
livecd gentoo # date 030600162006 (Format is MMDDhhmmYYYY)
Mon Mar  6 00:16:00 UTC 2006

Next, download a stage3 (see the top of this page for the official Gentoo sources, again). You can find it on my mirror in my x86 stage3 directory. And likewise a snapshot of the Portage tree. Then extract the contents of the stage3 tar file to /mnt/gentoo and the contents of the portage tar file to /mnt/gentoo/usr.

Download the stage3 archive

livecd gentoo # wget http://www.marslett.us/gentoo-distfiles/releases/x86/current-stage3/stage3-i686-*.tar.bz2
livecd gentoo # wget http://www.marslett.us/gentoo-distfiles/snapshots/portage-latest.tar.bz2
livecd gentoo # tar xjpf stage3*
livecd gentoo # cd usr
livecd gentoo # tar xjpf ../portage*.bz2

At this point the new Gentoo installation should be functional (but not bootable). Mount the /proc & /dev file systems, copy over the /etc/resolv.conf file, then chroot into the freshly built Gentoo environment.

Magical CHROOT!

livecd usr # cd /mnt/gentoo
livecd / # mount -t proc proc proc
livecd / # mount --rbind /dev dev
livecd / # cp -L /etc/resolv.conf etc

livecd / # chroot . /bin/bash
livecd / # env-update && . /etc/profile
>>> Regenerating /etc/ld.so.cache...

Set the root password, the time zone information, host name and domain name. And edit your /etc/fstab, replacing BOOT, ROOT and SWAP with the actual partition names. Don't forget to check that the file systems specified match the installation.

Setting up the minimum changes to /etc

(Set the permanent password)
livecd / # passwd
New UNIX password: type_a_password
Retype new UNIX password: type_a_password
passwd: password updated successfully

(Find the file to copy)
livecd / # ls /usr/share/zoneinfo

(Using Chicago as an example)
livecd / # cp /usr/share/zoneinfo/America/Chicago /etc/localtime

livecd / # date
Wed Mar  8 00:46:05 CST 2006

(Set the host name - this computer's name)
(   Note that the "at.myplace" is the domain: marslett.us here)
livecd / # echo "127.0.0.1 mybox.at.myplace mybox localhost" > /etc/hosts
livecd / # sed -i -e 's/HOSTNAME.*/HOSTNAME="mybox"/' /etc/conf.d/hostname

(Use defined host name and check)
livecd / # hostname mybox
livecd / # hostname -f
mybox.at.myplace

livecd / # nano -w /etc/fstab

(after editing, this is a reasonable fstab)
/dev/sda1   /boot     ext2    noauto,noatime     1 2
/dev/sda3   /         ext3    noatime            0 1
/dev/sda2   none      swap    sw                 0 0

Get ready for the kernel compilation experience! Stage3 has most of what you need to have installed, but you will need genkernel (for building the RAMdisk) and gentoolkit (for things like revdep-rebuild).

Next install a kernel source (gentoo-sources is generally recommended, but git-sources is not that scary), configure it, compile it, install it and if needed, build the RAMdisk image.

Installing the first kernel

livecd / # emerge genkernel
livecd / # emerge gentoolkit
livecd / # emerge gentoo-sources
livecd / # cd /usr/src/linux
livecd linux # make menuconfig
(Configure your kernel)

livecd linux # make
livecd linux # make modules_install
livecd linux # make install

(If you need kernel modules to boot, build a RAMdisk)
livecd linux # genkernel --kerneldir=. ramdisk

For a static network configuration, configure the network in /etc/conf.d/net. Symlink the net.lo init script to net.eth0 and install it to the default run level. If there are more NICs, do the same for them.

Either edit /etc/conf.d/net with nano or use the following commands:

Configure networking

livecd linux # cd /etc/init.d
livecd init.d # ln -s net.lo net.eth0
livecd init.d # cd /etc/conf.d
livecd conf.d # echo 'config_eth0=( "192.168.1.10/24" )' >> net
livecd conf.d # echo 'routes_eth0=( "default via 192.168.1.1" )' >> net
livecd conf.d # rc-update add net.eth0 default

(For network drivers compiled as modules)
livecd conf.d # echo r8169 >> /etc/modules.autoload.d/kernel-2.6

(And to allow connecting via ssh after rebooting)
livecd conf.d # rc-update add sshd default

Edit /etc/conf.d/clock to define the time zone you used previously. Otherwse it may go away during a future emerge.

Check the system configuration in /etc/conf.d/rc, /etc/conf.d/keymaps and /etc/rc.conf. Then make any edits required.

Edit some config files as required

(set the time zone for future updates)
livecd conf.d # nano -w clock
TIMEZONE="America/Chicago"

livecd conf.d # nano -w rc
livecd conf.d # nano -w keymaps
livecd conf.d # nano -w /etc/rc.conf

Install a system logger like syslog-ng and a cron daemon like vixie-cron. Then add them to the default run level. And don't forget the file system utilities and network tools.

Note: Cron daemons depend on an MTA. mail-mta/ssmtp will be pulled in as a dependency. If you want to use another MTA, you might want to install it now. If you are in a hurry, let ssmtp be installed and remove it later when you install the MTA of your choice.

Installing a syslogger and cron daemon

livecd conf.d # emerge syslog-ng vixie-cron
livecd conf.d # rc-update add syslog-ng default
livecd conf.d # rc-update add vixie-cron default

livecd conf.d # emerge xfsprogs               (If you use the XFS file system)

livecd conf.d # emerge dhcpcd
livecd conf.d # rc-update add dhcpcd default  (If you need a DHCP client)

livecd conf.d # emerge ppp                    +(If you need PPPoE ADSL connectivity)

Installing Grub, Configuring It and Booting

Emerge grub and configure it.

Emerge grub and edit its configuration file

livecd conf.d # emerge grub
livecd conf.d # nano -w /boot/grub/grub.conf

Example grub.conf (old style)

default 0
timeout 10

title Gentoo
root (hd0,0)
kernel /boot/kernel root=/dev/sda3
initrd /boot/ramdisk.bz2

 

Installing classic grub

livecd conf.d # grub
Probing devices to guess BIOS drives. This may take a long time.

grub> root (hd0,0)
 Filesystem type is ext2fs, partition type 0xfd

grub> setup (hd0)
 Checking if "/boot/grub/stage1" exists... yes
 Checking if "/boot/grub/stage2" exists... yes
 Checking if "/boot/grub/e2fs_stage1_5" exists... yes
 Running "embed /boot/grub/e2fs_stage1_5 (hd0)"...  16 sectors are embedded.
succeeded
 Running "install /boot/grub/stage1 (hd0) (hd0)1+16 p (hd0,0)/boot/grub/stage2 /boot/
grub/menu.lst"... succeeded
Done.

grub> quit

Exit the chrooted environment, unmount all file systems and reboot:

And finally reboot

livecd conf.d # exit
livecd / # umount /mnt/gentoo/dev /mnt/gentoo/proc /mnt/gentoo/boot /mnt/gentoo
livecd / # reboot
(Remove the CD)

When the system has booted up, log in as root, and add one or more users for daily use with useradd.

Also, remove the ssh information for the former configuration and prepare for ssh usage in the future.

Add a new user

mybox ~ # useradd -g users -G lp,wheel,audio,cdrom,portage,cron -m john
mybox ~ # passwd john
New UNIX password: Set John's password
Retype new UNIX password: Type John's password again
passwd: password updated successfully

Connect to your new box from another PC

(On your second PC, clean up your known_hosts file because
your new box has generated a new definitive hostkey)
$ nano -w ~/.ssh/known_hosts

(Look for the IP of your new PC and delete the line,
then save the file and exit nano)

(Use the IP address of your new box)
$ ssh root@192.168.1.10
The authenticity of host '192.168.1.10 (192.168.1.10)' can't be established.
RSA key fingerprint is 96:e7:2d:12:ac:9c:b0:94:90:9f:40:89:b0:45:26:8f.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '192.168.1.10' (RSA) to the list of known hosts.
Password: type_the_password

Polish make.conf

Define my mirrors and define the number of concurrent compilation processes and the number of parallel emerges that may be run at this point.

My first make.conf

# These settings are for the first emerges as a new system is moved over to
# Gentoo.

CFLAGS="-O2 -march=native -pipe"
CXXFLAGS="${CFLAGS}"

# MAKEOPTS="-j3"
# EMERGE_DEFAULT_OPTS="--jobs=3"

# WARNING: Changing your CHOST is not something that should be done lightly.
# Please consult http://www.gentoo.org/doc/en/change-chost.xml before changing.
CHOST="i686-pc-linux-gnu"

ACCEPT_LICENSE="*"

#PORTDIR_OVERLAY="/home/cmarslett/my-portage"
#source /var/lib/layman/make.conf

SYNC="rsync://www.marslett.us/gentoo-portage"

GENTOO_MIRRORS="\
	http://www.marslett.us/gentoo-distfiles/ \
	ftp://distro.ibiblio.org/pub/linux/distributions/gentoo/ \
	http:/ftp.gentoo.bg/ \
	rsync://mirror.opteamax.de/gentoo/ \
	http://gentoo.mirrors.hoobly.com/ \
	http://distfiles.gentoo.org/"

If this is just another install. Put the final make.conf and /etc/portage tree in place, and do an "emerge @world". I usually have to do it twice, running the command "USE=-cups emerge @world" the first time because of conflicts.

Otherwise, now is a good time to enable or disable some USE flags (a few at a time). Run emerge -vpe world to list all currently installed packages and their enabled and disabled USE flags. Edit /etc/make.conf adding changes you need to make.

View USE flags in use and enable or disable some

mybox ~ # emerge -vpe world
(Portage displays the packages and their USE flags, as an example, let's disable fortran, and enable ipv6 and unicode)
mybox ~ # echo 'USE="nptl nptlonly ipv6 -fortran unicode"' >> /etc/make.conf

Recent versions of glibc use /etc/locale.gen to define locale settings.

Define locales

mybox / # nano -w /etc/locale.gen
mybox etc # locale-gen

Last but not least, you may want to alter the CFLAGS variable in your /etc/make.conf to optimise the code to your specific needs. Please note that using a long list of flags is rarely needed and can even lead to a broken system. I specify the processor type (often "native") in the march option and -O2 -pipe.

You may also want to switch to ~x86 or ~amd64 with the ACCEPT_KEYWORDS variabe. You should only do this if you can deal with the odd broken ebuild or package. Of course, if you do not do this and do "emerge -DuN @world" every few weeks, you'll see the same thing. If you'd rather keep your system stable, don't touch it!

What make.conf might look like, finally

# These settings are for my Latitude laptop (real work, that is).

CFLAGS="-O2 -march=native -pipe"
CXXFLAGS="${CFLAGS}"

LINGUAS="en_US en de zh_TW zh_CN"

MAKEOPTS="-j3"

EMERGE_DEFAULT_OPTS="--jobs=3"


# WARNING: Changing your CHOST is not something that should be done lightly.
# Please consult http://www.gentoo.org/doc/en/change-chost.xml before changing.
CHOST="x86_64-pc-linux-gnu"

# These are the USE flags that were used in addition to what is provided by the
# profile used for building.
USE="a52 aac acpi alsa avahi avcodec avformat \
     bash-completion bluray branding -berkdb \
     cairo cdda cddb cdr cups \
     dbus dc1394 device-mapper dshow dts dvd dvdr \
     emacs encode exif firefox flac \
     gdu gif gnome gpm gstreamer gtk hal \
     id3tag ieee1394 jack jpeg \
     -kde lcms ldap libcaca libnotify libv4l libv4l2 lightning lua \
     matroska mmx mng mp3 mp4 mpeg ncurses nsplugin ntfs-3g ogg opengl oss \
     pam pango pdf png ppds policykit \
     samba schroedinger sdl spell sqlite stream svg sse sse2 \
     theora tiff truetype twolame udev unicode usb \
     v4l v4l2 vlm vorbis waveout wifi win32codecs wingdi wma-fixed \
     X x264 xml xulrunner xv xvid \
     threads"

ACCEPT_LICENSE="*"

# This is for the ebuilds that I could not get to work, and I need.
# Think of it as Gentoo hacking.
PORTDIR_OVERLAY="/home/cmarslett/my-portage"

# ---[Overlay Settings]--- #
source /var/lib/layman/make.conf

SYNC="rsync://www.marslett.us/gentoo-portage"

GENTOO_MIRRORS="\
	http://www.marslett.us/gentoo-distfiles/ \
	ftp://distro.ibiblio.org/pub/linux/distributions/gentoo/ \
	http://ftp.gentoo.bg/ \
	rsync://mirror.opteamax.de/gentoo/ \
	ftp://ftp.halifax.rwth-aachen.de/gentoo/ \
	http://gentoo.mirrors.hoobly.com/ \
	http://distfiles.gentoo.org/"

You might want to recompile your whole system twice to make full use of your latest configuration changes. It would take quite a long time to complete and yield minimal speed benefits. But recompiling is still a good idea from the standpoint of maintaining system consistency. See the Gentoo GCC Upgrading Guide for a discussion on the benefits of ensuring a consistently built system and world. You can also let your system rebuild itself gradually over time as new versions of packages are released.

Recompiling only the packages that have been updated or that are documented as affected by your new USE flags will take enough time. In either case you might have to remove packages that block your upgrade. Look for "[blocks B ]" in the output of emerge -vpuD --newuse world and use emerge -C to remove them.

If the block occurs right after adding or removing a USE flag, you may need to build one or another of the blocked packages with the new USE flag, then build the rest. You may even need to build a script to build the blocked packages in a manually specified order.

Update your packages


(Please note, switching to ~x86 will cause many packages to be upgraded)
mybox etc # emerge -vpDuN @world
(Take a good look at the package list and their USE flags,
remove blocking packages if any, and start the lengthy process)
mybox etc # emerge -DuN @world
(79 packages have been (re)compiled)

(AND remerge libtool to avoid further potential problems)
mybox etc # emerge -1 libtool

(Update config files, make sure you do not let dispatch-conf
update config files you have edited)
mybox etc # dispatch-conf
mybox etc # update-etc

(If gcc has been updated, you should run gcc-config)
mybox etc # gcc-config -l
(and possibly select a new default version)
mybox etc # gcc-config i686-pc-linux-gnu-4.5.2

(If perl has been updated, you should run the perl-cleaner script)
mybox etc # perl-cleaner all

(In case of a major upgrade of python, you should run the python-updater script)
mybox etc # python-updater

Installing Virtual Machine Systems

VirtualBox

You have to have the Sun/Oracle JDK 6.29 for Linux installed or alternatively build with "USE=-java" which will, incidentally, keep the debug console from working. This is because some of the java code violates the Sun Java specs. And the 6.29 version of the spec will build something that works from the bad source code: other versions (or iced tea), don't do so well. Note that you may need to use "java-config -S" (and "java-config -L" to list the possibilities) in order to enable the 6.29 java compiler.

Install app-text/texlive-core (provides pdflatex for virtualbox) and run "texmf-update". Install makeself (2.1.5-r1 or newer). After both of these are installed, you will need to execute "source /etc/profile" to make them available to the "emerge virtualbox" and "emerge vboxgtk" commands.

Note that vboxgtk requires that you specify "**" as well as "amd64" or "x86" in the package.keywords directory/file before it will build (at least, that was my experience in early 2012). virtualbox-additions and virtualbox-modules only need to have the keyword "amd64" or "x86" set in the package.keywords directory/file.

The problem with the java code appears to be fixed in the 9999 version of virtualbox, but when I try to build it, I get errors building both the fr-FR and en-US versions of the User Manual. I suspect this is an issue resulting from the 9999 ebuild not being compatible with the 2011 version of pdflatex (that is, texlive).

To install a client OS into a virtual machine, execute the following two commands and whe you start up the virtual machine select all the configuration options you need. Note that you must be logged into an account that is a member of the vboxusers group.

Starting up a Virtual Box Session

   mybox ~ $ sudo modprobe vboxdrv
   mybox ~ $ VirtualBox
   

qemu-kvm

Install "aqemu" with "USE=kvm" if you are using qemu-kvm, without if you are using plain qemu. Mixing the two will definitely keep the build from finishing.

QEMU_*_TARGETS should also not specify a ppc or mips platform (I get 3 very consistent build errors if I specify either of these).

vmware

So far I have been able to build the open source version of vmware player but not the workstation version. My user name and password are not working and the reset support on the vmware web site don't seem to work.

I even tried to set up an entirely new user name and password and that did not work either!