Document Actions

Gentoo Install Guide

by David Hostetler [modified 20120320:16:48 (Tue)] [posted 20061109:13:00 (Thu)]

A detailed, step-by-step guide to installing Gentoo Linux on a PC.

Purpose

This guide is intended to demonstrate how to install the Gentoo variant of the GNU/Linux OS. It includes everything from formatting a virgin harddrive to configuring dual-boot (i.e. WinXP). The install is conducted as a Stage 3 install, in Gentoo terminology, meaning that you'll use a pre-compiled (i.e. binary) tool chain to bootstrap the system, but then subsequently re-compile the entire OS on the target machine. The Gentoo installation is generally considered 'hard' and if completed successfully will earn you 10 Master Class geek points. I used to exclusively do the Stage 1 install process, which was considered really hard (though in fact it wasn't), but apparently even the Gentoo folks considered it too hard - or at least too newbie-hostile, since they're actively discouraging its use now and are only officially supporting stage 3 installs.

Each step in the guide is intentionally verbose and explicit, to (hopefully) avoid pitfalls and stalls that might normally stem from an unfamiliarity with Linux and Gentoo. After completion, you'll have a system that possesses all of the basic functionality of the Gentoo distribution. I've included some extra features and capabilities that I generally always want on my systems, but for the most part what you'll have is still just a blank slate, ready for you to discover just what you want Gentoo/Linux to do for you. Furthermore, it's worth noting that I maintain this guide for two reasons: (a) I'm trying to contribute positively to the pandemic of knowledge infection that is fueled in large part by open-source software; and (b) I hate having to remember all of the obscure minutia associated with this kind of technical process, so I record it and use it as a reference. If others benefit from it, more's the better. As Zoidberg would say, "Hooray! I'm helping!"

Disclaimers

This guide assumes the following:

In general, you are not an idiot. Specifically you have a working knowledge of computers.
You know what components compose your PC. Much of the Gentoo process requires customized configuration based on the hardware involved. You need to know what you have, so figure it out before getting started.
You have at least a rudimentary working knowledge of linux and its shell environment. If you don't know what I meant when I just said 'shell environment', then quit now. I take for granted that you understand what is meant by terminology like: root, su, dhcp, etc, and that you know how to manipulate files from a shell environment.
You have a fully functioning internet connection (preferably a fully proxied LAN environment). The default process for the Gentoo install CD is to fetch network configuration information via DHCP. I ensure that this always works in my LAN environment, so I've never had to pursue other methods of conducting the Gentoo package downloads associated with the install. If DHCP doesn't work for you, you're on your own.
Since I mostly install Gentoo on AMD64 systems, that's what this guide describes best. Most of the steps are platform generic, so if you're using a different architecture this can still be a useful reference, though you'll probably have to rely more heavily on the official Gentoo install documentation (see references below). I've included variations on some steps to account for a classic x86 install.
Though I've made most of the steps explicit in a technical sense, I've not included much explanation of why any particular step is necessary or any background information related to the steps. Such content is better provided elsewhere and this guide is intended to be functionally concise, not a textbook. This guide is not intended to supplant the Gentoo handbook, but rather to provide a proven recipe I can follow anytime I want to install Gentoo.
Lastly, know what you're getting into. Installing an OS is not for the meek. If something doesn't work, you need to have the fortitude to pursue a solution. Every step of this guide worked - for me. If something doesn't work for you, don't panic, and don't get mad at me. Generally, everytime I go through this process myself, something different misbehaves, and does so in a way that's new to me.

Resources

The following is a short list of Gentoo and Linux-related resources that I have found to be useful. I recommend ignoring them for the time being and just giving the guide a shot. If you hit an obstacle, then refer back to these. This is also a valuable list as you pursue additional customization and capabilities for your new Gentoo system, and even for day-to-day maintenance of the system, both of which will invariably generate problems that you will not have previously encountered.

Official Gentoo Handbook: Useful parallel reference for installing Gentoo, and the first place you should look if you have to deviate from this guide.
Official Gentoo Documentation: Detailed documentation on a broad range of topics, from essential Gentoo basics to application-specific guides. Good place to go once you've finished this guide and are wondering what to do next.

Official Gentoo Forums: This has become the first place I look when I encounter a problem in Gentoo (or Linux in general). You may even spot a few of my posts (my username is dahoste).

Gentoo Wiki: A compilation of user contributed documentation for nearly anything Gentoo related. The content is rough around the edges compared to the official docs, but the breadth of topics covered is invaluable.
Gentoo Portage: Details for all of the packages in the portage tree (including USE flags, versions, etc..).
LinuxQuestions.org: Casts a bigger net than the Gentoo forums (obviously), and suffers from a less experienced userbase in general, but still a good place to look if you're stuck.

Conventions

The following formatting conventions are used throughout the guide:

The names of files, URLs, and explicit menu selection text will appear in fixed-width.

Commands that you will submit explicitly on a command-line prompt will appear in the following format:
- ```
syntax that you have to enter explicitly
```

Version

The version of Gentoo used with this guide is 20110708.

Guide

(Note - the steps are numbered for the sake of referencing them, not to indicate a strict ordering, though it is assumed that they are performed in the order in which they're listed.)

[DUAL-BOOT] if you're planning on dual-booting to MS Windows, then install that first. If you've already got Windows installed, then you're nearly ready. You'll also need some available hard drive partitions to use for Gentoo. Ideally, you'll have either thought of that back when you installed Windows, leaving some of the harddrive unpartitioned, or you'll have an additional hard drive that you're going to dedicate to the Gentoo install. Below, I demonstrate how to create and format the partitions for Gentoo, but I assume that one of the two scenarios I just described exists. If you've only got one harddrive, and it's already full and/or fully-partitioned, then dealing with that situation is beyond the scope of this guide. My recommendation would be to just go buy another hard drive. There are, however, tools that allow you to repartition a hard drive 'out from under' Windows, but I've not used them and the very concept gives me the willies.
Download and burn a Gentoo Minimal CD (something along the lines of install-amd64-minimal-20110708.iso). Be sure to pick the correct architecture (i.e. x86 for 32bit, amd64 for 64bit, etc.).
Boot the CD, and enter the following at the boot prompt:
- ```
gentoo
```
Change the root password:
- ```
passwd
```
If you want to conduct the install remotely from another machine, you can start the ssh server via:
- ```
/etc/init.d/sshd start
```
- This will create a public/private key pair and start sshd. Then use:
  - ```
  ifconfig | grep "inet addr"
```
- This will show you what IP address the machine is using. There will probably be two, 127.0.0.1 which is the localhost addr, and another, which is the one you'll use to access the machine remotely. Then, use your ssh client of choice on another machine and login as root (using the password you just set previously).
If you're behind a proxy, you can establish it for this first phase of the install via the following (where proxy.domain.com:80 is your proxy URL):
- ```
export http_proxy="http://proxy.domain.com:80"
```
Now we're going to partition the harddrive(s). I prefer cfdisk, and the following examples are for a single SATA drive, /dev/sda (if you've got an IDE drive, you'll likely use /dev/hda).
- ```
cfdisk /dev/sda
```
- I typically create a ~100MB boot partition. For swap, I usually set aside 2xRAM, so for a 4GB RAM machine, I'd have 8GB swap. The rest I use for /. Alternatively, you might set aside the majority of the drive for /home, and leave a reasonable chunk for /. Having /home as a separate partition allows you to make radical changes to the Linux install while preserving nearly all of the custom (i.e. potentially irreplaceable) files. Depending on how sensitive you are to risk of unanticipated drive overflow, you might also dedicate a partition to /var/log and /tmp.
- Use the arrow keys to highlight the menu choices in cfdisk. The swap partition is type 82. All others should be type 83 (unless you're doing RAID, which isn't covered here - but just FYI, 0.90 metadata RAID is type fd and 1.2 metadata RAID is type da).
- Be sure to set the Bootable flag on the boot partition.
- [DUAL-BOOT] if your drive already has Windows installed on it, then be sure to leave that partition alone (it should be the first partition and it should have the Bootable flag set). DO NOT set the Bootable flag on any of the other partitions - i.e. the Windows partition should remain the only bootable partition.
- Be sure to Write the table before quitting cfdisk, to have your changes take effect. You'll see a warning about rebooting. You can reboot if you're feeling paranoid (just be sure to redo the passwd and sshd steps), or just continue to formatting - I've never had any problems skipping the reboot (but it may depend on the degree to which the drive is repartitioned).
Format your new partitions. I use ext2 for the boot partition, and ext3 for the others. For the following examples, /dev/sda1 is the boot partition, /dev/sda2 is swap, and /dev/sda3 will be used as /.
- ```
mke2fs /dev/sda1
mke2fs -j -O dir_index /dev/sda3
```
- Setup the swap:
  - ```
  mkswap /dev/sda2
  swapon /dev/sda2
```

Mount the new partitions:

mount /dev/sda3 /mnt/gentoo
mkdir /mnt/gentoo/boot
mount /dev/sda1 /mnt/gentoo/boot

Verify the system date:
- ```
date
```
- You should see something like: Mon Jan 1 10:30:00 UTC 2012
- If the date isn't correct, you can set it via the following (obviously, use the correct date):
  - ```
  date -s "Jan 01 10:30:00 MST 2012"
```
- Note: your BIOS date should be set to GMT (eastern is GMT-4) (see http://wwp.greenwichmeantime.com/).
- [DUAL-BOOT] if you're going to be dual-booting to Windows, you'll want to have the BIOS date set to your actual local time.
Get the stage 3 tarball (assuming you're doing a stage 3 install, which we are):
- ```
cd /mnt/gentoo
links2 -http-proxy proxy.domain.com:80 http://www.gentoo.org/main/en/mirrors.xml
```
- Note: only include the proxy argument if in fact your internet access is through a proxy.
- Pick a mirror (use the arrow keys to highlight and press Enter if the mouse doesn't work) and browse to:
  - For x86:
    - releases/x86/current-stage3/
  - For AMD64:
    - releases/amd64/current-stage3/
  - download stage3-<arch>-yyyymmdd.tar.bz2 (note: replace yyyymmdd with the current date listed)
While you've got links2 up and connected to a mirror, also grab the latest portage snapshot:
- Navigate back to the top of the mirror (/gentoo)
- Fetch: snapshots/portage-yyyymmdd.tar.bz2 (where yyyymmdd represents the most current tarball available)
Quit links2 (q) and unpack the stage tarball:
- ```
tar -xvjpf stage3-<arch>-yyyymmdd.tar.bz2
```
Go ahead and unpack the portage tarball as well:
- ```
tar -xvjf portage-yyyymmdd.tar.bz2 -C /mnt/gentoo/usr/
```
- Unpacking the portage snapshot takes awhile.
- You can delete both the stage3 and portage tarballs now if you want.
Create a few directories that we'll reference in our main system configuration file (make.conf):
- ```
mkdir /mnt/gentoo/usr/local/portage
```
- The following should already exist (if it doesn't, create it as you did the previous one):
  - ```
  /mnt/gentoo/var/log/portage
```
Now, configure /mnt/gentoo/etc/make.conf:
- ```
nano -w /mnt/gentoo/etc/make.conf
```
- Note: you can use the following for reference:
  - /mnt/gentoo/etc/make.conf.example(same as /usr/share/portage/config/make.conf.example, post installation)
  - /mnt/gentoo/usr/portage/profiles/use.desc(same as /usr/portage/profiles/use.desc, post installation)
  - run 'cat /proc/cpuinfo' to get a summary of your CPU
  - Gentoo-Portage Wiki
- It's particularly important that you use an appropriate 'march' setting. See the Safe Cflags article on the Gentoo Wiki.
- The contents of make.conf should be similar to the following:
  - ```
  CHOST="x86_64-pc-linux-gnu"
  CFLAGS="-march=amdfam10 -pipe -O2"
  CXXFLAGS="${CFLAGS}" # for MAKEOPTS, typically use -jn, where n = the number of CPUs+1
  MAKEOPTS="-j5"
  PORTDIR_OVERLAY=/usr/local/portage
  PORTDIR=/usr/portage
  DISTDIR=${PORTDIR}/distfiles
  
  # For the rsync server, only the GENTOO_MIRRORS line should be active.
  # For an rsync client, only the SYNC line should be active.
  #SYNC=rsync://192.168.1.1/gentoo-portage
  GENTOO_MIRRORS="http://distfiles.gentoo.org \
  http://www.ibiblio.org/pub/Linux/distributions/gentoo"
  
  # Settings for http-replicator (this setting is necessary for both the server and all clients):
  # (leave disabled for now if this system is going to be the proxy)
  #http_proxy="http://192.168.1.1:8080"
  
  # For USE, the following are optional based on CPU architecture: 3dnow mmx sse sse2
  # You can use 'cat /proc/cpuinfo' to see what features your CPU supports.
  USE="3dnow mmx sse X acpi apm apache2 python perl java gtk dvd dvdr ssl \
  nptl nptlonly alsa oss truetype ncurses crypt libwww zlib xml \
  kerberos ldap cups nls acl gd gpm jpeg nsplugin mozilla mysql mysqli php \
  posix postgres png qt4 samba sharedmem gdbm sockets unicode usb wxwindows \
  maildir imap readline tcpd pam pdf bash-completion xulrunner graphviz \
  vorbis opengl openal imlib lame flac vim-syntax \
  -firefox -kde -gnome -selinux -ipv6"
  
  # Add settings to enable portage logging:
  PORT_LOGDIR=/var/log/portage
  PORTAGE_ELOG_CLASSES="info warn error log"
  # note: we'll add email to the portage logging later, after we've configured an MTA
  PORTAGE_ELOG_SYSTEM="save"
  #PORTAGE_ELOG_MAILURI="root@localhost localhost"
  #PORTAGE_ELOG_MAILSUBJECT="[portage] \${HOST}: log for \${PACKAGE}"
  
  # Don't hog the system:
  PORTAGE_NICENESS = 19
  
  # add settings to reduce X11 driver bloat:
  INPUT_DEVICES="evdev"
  VIDEO_CARDS="vesa"
```
- Note: you'll only need either the SYNC or GENTOO_MIRRORS option, not both. Use GENTOO_MIRRORS if you'll be configuring this system as a local portage rsync mirror (which is recommended, unless you already have a server doing that).
- Note: the http_proxy option presumes that you'll be using a tool called http_replicator to establish a system on your LAN (possibly this system) as a local portage package mirror (which is also recommended unless you already have a server doing that). If you're not going to use http_replicator, then just omit this option (unless of course you need an http proxy for some other reason). See the HTTP Replicator post on the Gentoo forums for more information about this tool (I'll show you how to install and configure it later).
- Note: the VIDEO_CARDS option can include another driver besides just 'vesa', specifically one that is suited to your particular video card. To find a definitive list of the possible drivers, run the following and observe all of the options listed.
  - ```
  emerge -pv xorg-server
```
- If you're not going to establish the system as a local portage rsync mirror (and you don't have already have one on your LAN), then instead of the above SYNC/GENTOO_MIRROR settings, use the following to establish correct settings:
  - ```
  mirrorselect -i -r -o >> /mnt/gentoo/etc/make.conf
  mirrorselect -i -o >> /mnt/gentoo/etc/make.conf
```
- Those commands pop up a UI allowing you to pick a mirror, and will automatically add the corresponding options to the end of make.conf.
- You might want to do a 'cat /mnt/gentoo/etc/make.conf' and verify that the mirrorselect actions didn't bugger up the file (hopefully it's mature enough now to have stopped doing that).

Copy network settings:

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

Mount a few special filesystems:

mount -t proc none /mnt/gentoo/proc
mount -o bind /dev /mnt/gentoo/dev

Chroot into the new environment:
- ```
chroot /mnt/gentoo /bin/bash
```
If needed, re-establish the http_proxy (permanently) by editing one of the following two files:
- ```
nano -w /etc/skel/.bashrc
nano -w /etc/profile
```
- Add the following line to whichever file you decided to edit (again - use the currect URL for your proxy):
  - export http_proxy="http://proxy.domain.com:80"

Finish chrooting:

env-update
source /etc/profile
export PS1="(chroot) $PS1"

Set the timezone:
- Examine the available timezones:
  - ```
  ls /usr/share/zoneinfo
```
- Set the correct timezone (the example here is for Eastern Daylight Savings):
  - ```
  cp /usr/share/zoneinfo/EST5EDT /etc/localtime echo "EST5EDT" > /etc/timezone
```
Now update the portage tree (the Gentoo package database):
- ```
emerge --sync
```
- If that doesn't seem to be working (can't connect to an rsync mirror, due to proxy/firewall issues), then try:
  - ```
  emerge-webrsync --sync
```
- This takes a long time.
- Depending on how old the stage3 tarball is, you might finish with a warning that portage needs updating. We can do that now:
  - ```
  emerge --ask portage
```
- If that finishes with a message that files in /etc need updating, then do the following (use the provided prompts to update the files):
  - ```
  etc-update
```
Update/change the Gentoo system profile if you want to:
- View the current profile setting:
  - ```
  eselect profile list
```
- Change it to a different profile:
  - ```
  eselect profile set 2
```
- Details of the various profiles can be examined in the following location:
  - ```
  /usr/portage/profiles
```
Minimize the locales:
- You might have to update glibc before you can establish the locales (the way to tell is if the locale-gen program doesn't yet exist, you need to update glibc). This might take a long time. If you don't have to update glibc, then just skip to editing the '/etc/locale.gen' file
  - ```
  emerge --ask glibc
```
- If that finishes with a message that files in /etc need updating, then use the following (use the provided prompts to update the files):
  - ```
  etc-update
```
  - Now you can do:
    - ```
    rm /etc/locales.build
```
- Wether or not you updated glibc, edit the following file:
  - ```
  nano -w /etc/locale.gen
```
- Uncomment the locales that you want your system to support:
  - ```
  en_US ISO-8859-1
  en_US.UTF-8 UTF-8
```
- Run 'locale.gen' to actually generate the locales:
  - ```
  locale-gen
```

Fetch the kernel headers:

USE="-doc symlink" emerge -avt gentoo-sources

Identify the hardware on the system, and what modules were loaded by the Gentoo CD:
- ```
emerge -avt pciutils
```
- You can now run the following to get a summary of the PCI devices installed on the system:
  - ```
  lspci
```
- If the description for a device is ambiguous (or it's outright unidentified) you might be able to cross-reference the PCI IDs list.
- You can also use the following to see which modules were loaded by the Gentoo CD:
  - ```
  lsmod
```
Configure the kernel:
- ```
cd /usr/src/linux
make menuconfig
```
  - While the defaults are pretty good, you'll need to do some exploring here and catch any specific kernel options that pertain to your system. Yes, the first time you ever do this it's confusing, boring, and frustrating.
    - Be sure to specify the correct architecture for 'Processor type and features'.
    - The 'Device Drivers' and 'File Systems' sections are good places to look for additional options.
    - It's particularly important that you select the correct filesystem support, so that the system can mount the partitions successfully at boot.
    - If you're using a USB mouse and/or keyboard, you'll be particularly annoyed later if you don't correctly enable the USB options under 'Device Drivers -> USB support'. The important one is 'USB Human Interface Device (full HID) support'.
- ```
make && make modules_install
```

Now copy the new kernel into place. Be sure to use the correct kernel version, rather than what's shown here. Also, for x86, the directory is 'x86' instead of 'x86_64'.

cp arch/x86_64/boot/bzImage /boot/kernel-2.6.39-gentoo-r3-yyyymmdd
cp System.map /boot/System.map-2.6.39-gentoo-r3-yyyymmdd
cp .config /boot/config-2.6.39-gentoo-r3-yyyymmdd

You're unlikely to get the kernel configured entirely to your needs/liking the first time. Just reconfigure the kernel and rebuild it as many times as you need, if you discover after booting that you missed something. I'll describe further down how to recover from a failed first-boot.
You might need to emerge some additional 3rd party kernel modules:
- Like a video driver:
  - ```
  emerge -avt ati-drivers
```
- Or...
- ```
emerge -avt nvidia-drivers
```
- You can find any newly-built modules (if you specified any of the options in the kernel config to be built as modules) via the following:
  - ```
  find /lib/modules/ -type f -iname '*.o' -or -iname '*.ko'
```
- Include modules you want loaded at boot via the following:
  - ```
  nano -w /etc/conf.d/modules
```
- Just add the names of the modules to the list (i.e. modules="nvidia fglrx agpgart", etc..).
- Commit changes to /etc/conf.d/modules:
  - ```
  update-modules
```
- Anytime you rebuild your kernel, you'll need to have dependent modules rebuilt as well. There's an easy way to set this up.
  - ```
  emerge -avt module-rebuild
  module-rebuild populate
```
- Now anytime you change the kernel, you can just do:
- ```
module-rebuild rebuild
```

Formalize your mounts points (use 'man mount' and 'man fstab' for details):

```
nano -w /etc/fstab
```

Here's what mine looks like:

/dev/sda1               /boot           ext2            defaults,noatime        1 2
/dev/sda2               none            swap            sw                      0 0
/dev/sda3               /               ext3            noatime                 0 1
/dev/cdrom              /mnt/cdrom      auto            noauto,user             0 0
192.168.1.2:/raid/home  /home           nfs             rw,hard,intr            0 0
/dev/sdb1               /backup         ext3            noatime                 0 1
shm                     /dev/shm        tmpfs           nodev,nosuid,noexec     0 0

Configure network:

nano -w /etc/conf.d/hostname
nano -w /etc/conf.d/net

Here's what mine looks like:

# see /etc/share/doc/openrc-<version>/net.example for details on configuration options.

# (hoss) as either server or client:
config_eth0="dhcp"

# (hoss) as server:
dhcp_eth0="norelease nodns nontp nonis nosendhost"
dhcpcd_eth0="-t 10"
config_eth1="192.168.1.1/24 broadcast 192.168.1.255"

Ensure that networking starts automatically during boot:
- ```
ln -s net.lo net.eth0
rc-update add net.eth0 default
```
If you've got additional network interfaces on the system, you can exploit the single /etc/conf.d/net file to configure all of them:
- ```
ln -s net.lo net.eth1
rc-update add net.eth1 default
```
- Then just be sure to edit /etc/conf.d/net to include options for the other interfaces (i.e. add 'config_eth<n>' and 'dhcp_eth<n>', etc. for each interface <n>).
```
nano -w /etc/hosts
```
- Here's what mine looks like:
  - ```
  127.0.0.1       leaf.negativesum.net leaf localhost
```
- Note: if you're running DNS for your lan, you don't need to edit this at all.

Reset the root password (remember when we did it before, it was for the boot CD session, we've since chroot'ed):
- ```
passwd
```
Edit rc.conf.
- ```
nano -w /etc/rc.conf
```
- Set the EDITOR value to your choice. For example:
- ```
EDITOR="/usr/bin/vim"
```
Set the XSESSION variable, system-wide.
- ```
nano -w /etc/env.d/90xsession
```
- Set the XSESSION value to the window manager of your choice. For example:
- ```
XSESSION="fluxbox"
```
Verify that /etc/conf.d/keymaps is correct (the defaults usually suffice):
- ```
nano -w /etc/conf.d/keymaps
```
Verify that /etc/conf.d/hwclock is correct (the defaults usually suffice):
- ```
nano -w /etc/conf.d/hwclock
```
- Use CLOCK="UTC" if your bios clock is GMT.
- [DUAL-BOOT] use CLOCK="local" if your bios clock is local time, which should only be the case if you dual-boot to a windows partition.

Configure the bootloader (I like GRUB instead of LILO)

Note that extended partitions will 'consume' a partition number, as far as grub is concerned. I.e. if you have 2 primary partitions and then an extended partition which itself contains 2 logical partitions, then the first 2 primary partitions will be (hd0,0) and (hd0,1); the extended partition would be (hd0,2) but won't actually be displayed by grub; and the 2 logical partitions will be (hd0,3) and (hd0,4).

emerge -avt grub
cp /boot/grub/grub.conf.sample /boot/grub/grub.conf
nano -w /boot/grub/grub.conf

default 0
# How many seconds to wait before the default listing is booted.
timeout 30
# comment out the splash image if you don't have a graphics card installed
splashimage=(hd0,0)/grub/splash.xpm.gz
# first boot option:
title=Gentoo Linux
# Partition where the kernel image is located
root (hd0,0)
kernel /kernel-2.6.34-gentoo-r1-20100718 root=/dev/hda3

# [DUAL-BOOT]: uncomment the following for a windows boot in the primary partition.
#title Windows XP
#rootnoverify (hd0,0)
#chainloader +1

Install the bootloader

Manually (recommended by the grub docs, over the grub-install method):

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

Using grub-install:

grep -v rootfs /proc/mounts > /etc/mtab
grub-install --no-floppy --root-directory=/boot /dev/hda

Almost ready for launch - we've got to install a few system tools prior to the first boot:

emerge -avt dhcpcd metalog vixie-cron nfs-utils mdadm lvm2
rc-update add metalog default
rc-update add vixie-cron default
rc-update add sshd default
rc-update add nfsmount default

Add a normal user account (replace <user> with your preferred user name):

useradd -d /home/<user> -m -G users,wheel,cdrom,audio,video,cron <user>
passwd <user>

Done! Exit chroot'ed env and reboot:
- ```
exit
cd
umount /mnt/gentoo/boot /mnt/gentoo/dev /mnt/gentoo/proc /mnt/gentoo
```
- If you have been using a remote ssh shell to conduct the install, you can either submit the reboot command from it (which will kill the ssh connection) or you can exit the remote connection manually, and go submit the reboot command directly from the console on the target system:
```
reboot
```
When the system reboots, login as root
If for some reason the system doesn't boot correctly, you have to go into trouble-shooting mode. If it seems to boot correctly, but you can't login, or you see messages that cause you to suspect that you're missing some key kernel options (wrong/missing drivers, etc.) then you'll need to reboot to the Gentoo install CD, and go through a few of the first steps (namely mounting your already created partitions, and chrooting in) in order to reconfigure and rebuild the kernel and try again. Specifically, redo the following steps: 2,3,4, the swapon portion of 7, the mount portions of 8, 17, 18, 20, and finally 27 and 28 to make changes to the kernel. Then skip to 41 and try rebooting again. Wash, rinse, repeat as necessary.

Once you're able to reboot and successfully login, do a big system refresh (this will take a long time)

First we need to indicate to gentoo that we want the most recent available version for certain packages, regardless of whether they've been fully tested by gentoo. You'll want to read more about emerge and portage and package management to fully understand the masking, unmasking, and keyword mechanisms, but the general concept here is that package versions first show up with a 'testing' flag and spend a certain amount of time in that condition before being categorized as 'stable' and available for general consumption by the gentoo populace. In certain circumstances (if you're familiar with the package and its upstream maintanance and development) it's desirable to just let your system get the updated versions as soon as they're available rather than waiting for them to acquire the 'stable' status.
- Include the following in /etc/portage/package.keywords:
  - ```
  app-emulation/wine ~x86
  dev-python/reportlab ~x86
  net-nds/phpldapadmin ~x86
  net-nds/smbldap-tools ~x86
  dev-perl/Unicode-MapUTF8 ~x86
  media-gfx/graphviz ~x86
  app-doc/doxygen ~x86
  x11-wm/fluxbox ~x86
  x11-themes/slim-themes ~x86
  net-misc/curl ~x86
  media-gfx/imagemagick ~x86
  dev-python/python-openid ~x86
  www-apache/mod_wsgi ~x86
  dev-python/configobj ~x86
  dev-python/virtualenv ~x86
  media-sound/alsaplayer ~x86
  sys-apps/ethtool ~x86
```

Now provide some customizations to how certain packages are compiled. Edit /etc/portage/package.use:

dev-lang/python sqlite tk
net-misc/ntp caps
www-servers/apache ldap ssl static suexec
x11-libs/cairo svg -xcb
x11-wm/fluxbox imlib
app-admin/conky X truetype audacious hddtemp vim-syntax -ipv6
net-fs/samba cups ldap pam python readline ads automount swat winbind
app-emulation/virtualbox additions alsa
dev-cpp/gtkmm accessibility
dev-db/mysql -berkdb embedded
net-analyzer/tcpdump -samba

# doxygen
app-doc/doxygen latex tetex
app-text/texlive extra
media-libs/freetype kpathsea
app-text/lcdf-typetools kpathsea

# avahi-related stuff
net-dns/avahi qt3 mdnsresponder-compat
kde-base/kdelibs avahi

# for pdftk:
sys-devel/gcc gcj

# fix for GCC4.2+ requirement:
x11-libs/pixman -sse2

# for firefox >=3.5 upgrade, and the '-eds' because otherwise ooffice crashes.
media-video/vlc -nsplugin
app-office/openoffice -nsplugin -eds
dev-db/sqlite fts3

# for ffmpeg theora support:
media-video/ffmpeg vhook theora threads

# temp? for gnome stuff:
net-libs/libsoup gnome
gnome-base/gvfs gnome

# for kdiff3:
x11-libs/qt-qt3support kde
x11-libs/qt-webkit kde

Some packages require specific license acceptance. Edit /etc/portage/package.license:

dev-java/sun-jdk dlj-1.1
app-emulation/virtualbox-additions PUEL
www-plugins/adobe-flash AdobeFlash-10.1net-im/skype skype-eula

Now it's clear to do the big system refresh:

emerge --ask --update --deep --newuse --fetchonly world
emerge --update --deep --newuse world

Now pull in a bunch of new stuff (the following are all strongly recommended, for either a server or a desktop system):

emerge -avt \
portage-utils xorg-x11 fluxbox iptables gentoolkit samba shorewall rdiff-backup \
lshw vim gvim wxpython ntp xlockmore bind-tools logrotate mailx \
mutt rdesktop alsa-oss rxvt-unicode vim-spell-en sudo p7zip unrar \
lafilefixer ethtool jwhois eclass-manpages

The following additional packages are recommended if you're setting up a server:

emerge -avt \
dhcp dev-db/mysql postgresql mysql-python apache dev-lang/php php-docs mod_python

The following packages are recommended if you're setting up a software development system:

emerge -avt \
kdiff3 bzr bzrtools bzr-explorer subversion doxygen poedit boost epydoc pydb \
pyflakes pylint sphinx dev-python/imaging

The following packages are recommended if you're going to be playing games:
- ```
emerge -avt \
dosbox timidity++ wine
```

And the following are extras that aren't strictly necessary but I've discovered that I generally always want to install:

emerge -avt \
conky hddtemp audacious audacity filezilla xchat virtualbox openoffice \
blender gimp gqview easytag grip mpg123 xcalc alsamixergui cdrtools eterm \
xpdf xchm xv mumble xchat deluge mozilla-firefox chromium

Depending on which of those packages you actually added, you might need to update your kernel modules. Virtualbox is a good example. If new kernel modules are needed, edit /etc/modules.autoload.d/kernel-2.6 and add any new modules:
- ```
agpgart
intel-agp
radeon
vboxdrv
vboxnetflt
vboxnetadp
```
Then update the module-related utilities:
- ```
update-modules
module-rebuild populate
```

Install http-replicator (only if this machine is going to proxy gentoo package updates to other machines on your lan)
- See the forum thread for more info.
- See the gentoo-wiki article.
- ```
emerge --ask http-replicator
```
- Follow the instructions given at the end of the emerge.
  - Verify /etc/conf.d/http-replicator is kosher. Probably the only thing you'll need to set is the following:
    - ```
    ## The ip addresses from which access is allowed. Can be used as many times
    ## as necessary. Access from localhost is allowed by default.
    DAEMON_OPTS="$DAEMON_OPTS --ip 192.168.1.*"
```
- Fun the following to seed the replicator cache:
  - ```
  /usr/bin/repcacheman
```
  - Some packages in portage have a RESTRICT="nomirror" option which will prevent portage from checking replicator for those packages. To override this behavior, put the following in /etc/portage/mirrors (note - if you already have a local setting, don't worry, as long as it is an http mirror it will still be effective):
    - ```
    # Http-Replicator Override for FTP and RESTRICT="nomirror" packages
    local http://gentoo.osuosl.org
```
- Add it to the default runlevel and start it up:
  - ```
  rc-update add http-replicator default
  /etc/init.d/http-replicator start
```
- You're now hosting a nice gentoo portage mirror, from which other gentoo boxes on your lan can easily fetch packages, without unnecessary wan traffic.
- After every emerge (not emerge --sync), you want to run repcacheman to keep the cache up to date and distfiles clean, i.e.:
- ```
emerge -uDva world && repcacheman
```

Enable some convenient bash completion options:

eselect bashcomp enable --global vim gvim bzr eselect ooffice xxd dbus

Add a few new services to the default runlevel:
- ```
rc-update add dbus default
```
Configure the audio volume:
- ```
alsamixer
```
- 'm' will unmute a muted column. Arrow keys raise/lower the volume. 'ESC' quits.
- Use mpg321 to test output:
  - ```
  mpg123 <somesong>.mp3
```
- Hopefully you heard audio. If not, welcome to linux audio hell. If so, congratulations! Save the alsa settings, and add the audio services to the boot level:
  - ```
  /etc/init.d/alsasound save
  rc-update add alsasound boot
  rc-update add timidity default
```
Enable post-sync ebuild cache reinitialization (if you emerged portage-utils):
- ```
chmod u+x /etc/portage/postsync.d/q-reinitialize
```
Anything else?

Configuring X11

These are just the rudimentary steps to get X up and running and have the mouse usable. To get it truly tricked out you're on your own.

Gentoo X11 Documentation

The mouse device is probably /dev/input/mouse0 (or /dev/input/mice). You can test by doing 'cat /dev/input/mouse0' and moving the mouse - if you get garbage, then that's the right dev. Note: when using a (USB) kvm, I've found that after switching, '/dev/input/mice' is the USB input that picks the mouse back up, so try using that instead of '/dev/input/mouse0' if you're having trouble.

Get Xorg to probe the system and spit out a conf file to start with:
- ```
Xorg -configure
```

That will create /root/xorg.conf.new. You need to copy it to the right place and customize it.

cp /root/xorg.conf.new /etc/X11/xorg.conf
vim /etc/X11/xorg.conf

Identifier  "Mouse1"
Driver      "mouse"
Option  "Protocol" "ImPS/2"
Option  "ZAxisMapping" "4 5"
Option  "Buttons" "5"
Option  "Device" "/dev/input/mice"

edit /etc/conf.d/xdm and uncomment the following line:
- ```
DISPLAYMANAGER="gdm"
```

Install slim and ensure xdm starts at boot:

emerge -avt gdm gdm-themes
rc-update add xdm default

Anything else?

Miscellaneous

if you're running your own mail server, edit /etc/crontab and change the email recipient:
- ```
MAILTO=root@<yourdomain.com>
```
- where <yourdomain.com> is the domain name serviced by your MTA
Convert the apache user to a full-blown user.
- edit /etc/passwd:
- edit /etc/shadow, copy the line for your new user login and then change the name to 'apache', so you get something like:
- edit /etc/group, add 'apache' to users, wheel, cron
- create the apache home directory
- You can now login as your apache user, and setup cron jobs for apache stuff (this will simplify permissions issues with your web content). If you're worried about apache being a 'real' user, you can disallow ssh access for it.
asdf

Application-specific Configuration Steps

Bash

Ensure that consoles are cleared when someone logs out.
- Edit /etc/bash/bash_logout and /etc/skel/.bash_logout, and include the following:
- ```
# Clear the screen for security's sake.
clear
```
Add any convenience aliases or other customizations to the shared bashrc.
- Edit /etc/bash/bashrc and /etc/skel/.bashrc, and include the following:
- ```
# added -hoss:
alias ll="ls -AFl"
alias lld="ls -AFld"
alias llt="ls -AFlt"
alias lldt="ls -AFldt"
alias e="gvim -geometry +10+10"
```

Evolution

If you installed thunderbird or evolution as your email client, you'll want to configure it to use your chosen browser to autolaunch URLs in emails:
- ```
gconftool-2 --set /desktop/gnome/url-handlers/http/command -t string 'xdg-open %s'
gconftool-2 --set /desktop/gnome/url-handlers/https/command -t string 'xdg-open %s'
```
- Replace 'firefox' with whatever browser you're using (if it isn't firefox).

Tips

run 'lshw' to see memory info (emerge lshw)
run 'free' to see memory info
run 'top' to see memory and process info
run 'df -h' to see disk volume usage
run 'du -hs' to see the cumulative size of specific directories
run 'lspci' to see devices (emerge pciutils)
run 'lsmod' to see installed modules (and dependencies)
run 'cat /proc/cpuinfo' to see CPU info
run 'cat /proc/meminfo' to see mem info
run 'uname -a' to see your kernel name
run 'rc-update show' to see which services will auto-run, at which levels
run 'rc-status' to see the operating status of those services
run 'equery depends <package name>' to see what other packages depend on a given package
run 'equery belongs <filename>' to see what package is responsible for a given file
look in /var/tmp/portage/<package> if there's an emerge error for <package>
look at /var/log/emerge.log for emerge messages
/var/lib/portage/world accumulates everything that you explicitly add to your system (i.e. that you include in an 'emerge' command)
use qlop to view emerge history for specific packages (qlop comes with portage-utils)
use equery to discern associates between files on the filesystem and packages
use qlist to get info on packages
use eclean to keep the package storage requirements under control
use the following when some packages state the x11 stuff needs to be rebuilt:
- ```
qlist -C -I x11-drivers | xargs -d '\n' emerge -vt mesa xorg-server
```
If you want/need to mount an NTFS partition with r/w privileges, you need fuse and ntfs3g:
- ```
emerge -avt sys-fs/fuse ntfs3g
mount -t ntfs-3g /dev/<hd> /mnt/<name>
```
What else...?

Fetching stage 2 &3

Posted by horny-sama at 20120113:00:39 (Fri)

The only problem I am encountering is fetching stage 2 & 3 using my wireless connection. *No wired connection in my university dorm! Anyways around it?

Posted by David Hostetler at 20120116:10:40 (Mon)

Unfortunately, I don't have much experience bootstrapping a system with only a wireless connection.

I would've thought, though, that while the gentoo LiveCD is running (i.e. while you're still chrooting the system that you're setting up, and before your first self-hosted boot) that its ability to easily maintain a wireless network connection would be sufficient to do what you need.

Posted by Hugo at 20120508:08:22 (Tue)

I just read that guide. Seems to be correct and very detailed. In point 25 (Minimize the locales) I would suggest that even if locale-gen doesn't exist to create a locale.gen file in the first place before updating glibc. If you just update glibc with an empty locale.gen, it creates every known locale which could easily take some hours to finish.

Sections

Personal tools