Gentoo Linux x86 with Software Raid and LVM2 Quick Install Guide

1. Introduction

This guide contains all commands you should use to complete a stage3 installation including LVM2 on top of software RAID. This guide is targeted at experienced users. You need a connection to the Internet to download the stage3 and Portage snapshots.

New users should read the Handbook as it gives a better overview about the installation process.

Timing output follows all commands that take more than a couple of seconds to finish. Commands were timed on an AMD 2000 1.66 Ghz PC with 512 Mb of RAM and two SATA disks connected to a hardware controller configured as JBOD (i.e. two separate hard disks are seen by Gentoo). If you have a "hardware" RAID controller on your motherboard, it is most likely not a hardware controller.

Code Listing 1.1: Test box specs

(The following specs and the timing information should help you determine
a rough estimate of the time you need to complete your install)

# grep bogo /proc/cpuinfo
bogomips       : 3337.81

# hdparm -tT /dev/sda /dev/sdb
/dev/sda:
reads:   1048 MB in  2.00 seconds = 524.00 MB/sec
 Timing buffered disk reads:  152 MB in  3.01 seconds =  50.50 MB/sec

/dev/sdb:
 Timing cached reads:   1048 MB in  2.00 seconds = 524.00 MB/sec
 Timing buffered disk reads:  152 MB in  3.01 seconds =  50.50 MB/sec

# grep MemTotal /proc/meminfo
MemTotal:       509248 kB

2. Quick Install Guide

Installation Media

Download a CD from one of our mirrors. You can find the minimal CD ISO in releases/x86/<release>/installcd or the LiveCD ISO in releases/x86/<release>/livecd. The minimal installation CD is only useful for Internet-based installations. You can use the LiveCD to perform a networkless installation as documented in the 2008.0 x86 installation handbook. The minimal CD is recommended.

Burn the CD and boot it.

Booting the CD

Press F2 at the boot screen to find out what boot options exist. You can either start gentoo or gentoo-nofb, the latter disables the framebuffer. If you booted the LiveCD, don't forget to add the nox option to prevent the X graphical environment from starting. Several options allow to enable or disable some features. If all goes well, your hardware will be detected and all modules will be loaded. If the kernel fails to boot properly or if your computer hangs during the boot procedure, you may have to experiment with different configurations. The safest way is probably to use the nodetect option and then load required modules explicitly.

Code Listing 2.1: Boot the minimal CD

Gentoo Linux Installation LiveCD                     http://www.gentoo.org
Enter to Boot; F1 for kernels  F2 for options.
boot: gentoo-nofb
  (or in case of problems)
boot: gentoo-nofb nodetect

Optional: loading modules

If you used the nodetect option, once booted, load the required modules. You need to enable networking and have access to your disks. The lspci command can help you identify your hardware.

Code Listing 2.2: Load required modules

livecd root # lspci
(Use lspci's output to identify required modules)

(The following is an example, adapt it to your hardware)
livecd root # modprobe 3w-9xxx
livecd root # modprobe r8169

Network Configuration

If your network does not work already, you can use net-setup to configure your network. You might need to load support for your network card using modprobe prior to the configuration. If you have ADSL, use pppoe-setup and pppoe-start. For PPTP support, first edit /etc/ppp/chap-secrets and /etc/ppp/options.pptp and then use pptp <server ip>.

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 using export http_proxy, ftp_proxy and RSYNC_PROXY.

Code Listing 2.3: Configure networking the guided way

livecd root # net-setup eth0

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

Code Listing 2.4: Configure networking the manual way

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

The installation CD allows you to start an sshd server, add additional users, run irssi (a command-line chat client) and surf the web using lynx or links.

Optional: connect to your new box over ssh

The most interesting feature is of course sshd. You can start it and then connect from another machine and cut and paste commands from this guide.

Code Listing 2.5: Start sshd

livecd root # time /etc/init.d/sshd start
 * Generating hostkey ...
(sshd generates the key and displays more output)
 * starting sshd ...                            [ok]

real   0m13.688s
user   0m9.420s
sys    0m0.090s

Now, set the root password on the liveCD so that you can connect to it from another PC. 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, you should use it only once as it will disappear after your first reboot.

Code Listing 2.6: 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, you can start a terminal on another PC and connect to your new box, follow the rest of this guide in another window, and cut and paste commands.

Code Listing 2.7: Connect to your 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 Disks

Load the software RAID and LVM2 modules.

Code Listing 2.8: Load RAID and LVM2 modules

livecd ~ # modprobe raid0
livecd ~ # modprobe raid1
(raid5, raid6 and raid10 are also available)

livecd ~ # modprobe dm-mod

Use fdisk or cfdisk to create your partition layout. The device names are likely to be either /dev/sda and /dev/sdb for a SATA or SCSI disks, or /dev/hda and /dev/hdb for IDE disks. The following layout will be used in this guide:

	/dev/sda	/dev/sdb	Type
/dev/md1	/boot	/boot	Raid-1 (mirroring)
	swap	swap	Normal partitions
/dev/md3	/	/	Raid-1 (mirroring)
/dev/md4	LVM2 volumes		Raid-0 (striped)

Important: The partition you boot from must not be striped. It may not be raid-5 or raid-0.

Note: On the one hand, if you want extra stability, consider using raid-1 (or even raid-5) for your swap partition(s) so that a drive failure would not corrupt your swap space and crash applications that are using it. On the other hand, if you want extra performance, just let the kernel use distinct swap partitions as it does striping by default.

Code Listing 2.9: Create the partitions

livecd ~ # fdisk /dev/sda
(Make sure you use type fd)

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

Disk /dev/sda: 299.9 GB, 299989204992 bytes
255 heads, 63 sectors/track, 36471 cylinders
Units = cylinders of 16065 * 512 = 8225280 bytes

   Device Boot      Start         End      Blocks   Id  System
/dev/sda1               1          11       88326   fd  Linux raid autodetect
/dev/sda2              12          61      401625   82  Linux swap / Solaris
/dev/sda3              62         311     2008125   fd  Linux raid autodetect
/dev/sda4             312       36471   290455200   fd  Linux raid autodetect

(Partition the second disk exactly as the first)
livecd ~ # fdisk /dev/sdb

Then create the RAID device nodes and devices:

Code Listing 2.10: Create device nodes and devices

livecd ~ # mknod /dev/md1 b 9 1
livecd ~ # mknod /dev/md3 b 9 3
livecd ~ # mknod /dev/md4 b 9 4

livecd ~ # mdadm --create /dev/md1 --level=1 --raid-devices=2 /dev/sda1 /dev/sdb1
mdadm: array /dev/md1 started.
livecd ~ # mdadm --create /dev/md3 --level=1 --raid-devices=2 /dev/sda3 /dev/sdb3
mdadm: array /dev/md3 started.
livecd ~ # mdadm --create /dev/md4 --level=0 --raid-devices=2 /dev/sda4 /dev/sdb4
mdadm: array /dev/md4 started.

(Wait until all units are ready)
livecd ~ # cat /proc/mdstat
Personalities : [raid0] [raid1]
md4 : active raid0 sdb4[1] sda4[0]
581006592 blocks 64k chunks

md3 : active raid1 sdb3[1] sda3[0]
1959808 blocks [2/2] [UU]

md1 : active raid1 sdb1[1] sda1[0]
88256 blocks [2/2] [UU]

Then create the LVM2 volumes in /dev/md4. The following scheme is used as an example:

Directory	Size	File system
/usr	8 GB	ext3
/usr/portage	2 GB	ext2, small block size, many inodes
/usr/portage/distfiles	4 GB	ext2, large block size, less inodes
/home	10 GB	ext3
/opt	4 GB	ext3
/var	4 GB	ext3
/var/tmp	6 GB	ext2
/tmp	2 GB	ext2

Code Listing 2.11: Create LVM2 volumes

livecd ~ # vgscan
  Reading all physical volumes.  This may take a while...
  No volume groups found
livecd ~ # vgchange -a y
  No volume groups found

(Create physical volumes, we have only one in our example)
livecd ~ # pvcreate /dev/md4
  Physical volume "/dev/md4" successfully created

(Create volume groups, again, we have only one in our example)
livecd ~ # vgcreate vg /dev/md4
  Volume group "vg" successfully created

(Create logical volumes)
livecd ~ # lvcreate -L8G -nusr vg
  /dev/cdrom: open failed: Read-only file system
  Logical volume "usr" created (Further similar messages not displayed)
livecd ~ # lvcreate -L2G -nportage vg
livecd ~ # lvcreate -L4G -ndistfiles vg
livecd ~ # lvcreate -L10G -nhome vg
livecd ~ # lvcreate -L4G -nopt vg
livecd ~ # lvcreate -L4G -nvar vg
livecd ~ # lvcreate -L6G -nvartmp vg
livecd ~ # lvcreate -L2G -ntmp vg

(Display volume groups and logical volumes)
livecd ~ # vgs
  VG   #PV #LV #SN Attr  VSize   VFree
  vg     1   8   0 wz--n 554.09G 514.09G
livecd ~ # lvs
  LV        VG   Attr   LSize  Origin Snap%  Move Copy%
  distfiles vg   -wi-a-  4.00G
  home      vg   -wi-a- 10.00G
  opt       vg   -wi-a-  4.00G
  portage   vg   -wi-a-  2.00G
  tmp       vg   -wi-a-  2.00G
  usr       vg   -wi-a-  8.00G
  var       vg   -wi-a-  4.00G
  vartmp    vg   -wi-a-  6.00G

Use mke2fs, mke2fs -j, mkreiserfs, mkfs.xfs and mkfs.jfs to create file systems. Initialize swap using mkswap and swapon.

Code Listing 2.12: Create the file systems and activate swap

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

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

(Create file systems on logical volumes)
livecd ~ # mke2fs -b 4096 -T largefile /dev/vg/distfiles
livecd ~ # mke2fs -j /dev/vg/home
livecd ~ # mke2fs -j /dev/vg/opt
livecd ~ # mke2fs -b 1024 -N 200000 /dev/vg/portage
livecd ~ # mke2fs /dev/vg/tmp
livecd ~ # mke2fs -j /dev/vg/usr
livecd ~ # mke2fs -j /dev/vg/var
livecd ~ # mke2fs /dev/vg/vartmp

(Create and activate swap)
livecd ~ # mkswap /dev/sda2 && mkswap /dev/sdb2
livecd ~ # swapon -p 1 /dev/sda2 && swapon -p 1 /dev/sdb2
(Check that all swap partitions use the same priority)
livecd ~ # swapon -v -s
Filename                   Type            Size    Used    Priority
/dev/sda2                  partition       401616  0       1
/dev/sdb2                  partition       401616  0       1

Mount the freshly created file systems on /mnt/gentoo. Create directories for the other mount points and mount them too.

Code Listing 2.13: Mount the file systems

livecd ~ # mount /dev/md3 /mnt/gentoo
livecd ~ # cd /mnt/gentoo
livecd gentoo # mkdir boot home usr opt var tmp
livecd gentoo # mount /dev/md1 /mnt/gentoo/boot
livecd gentoo # mount /dev/vg/usr /mnt/gentoo/usr
livecd gentoo # mount /dev/vg/home /mnt/gentoo/home
livecd gentoo # mount /dev/vg/opt /mnt/gentoo/opt
livecd gentoo # mount /dev/vg/tmp /mnt/gentoo/tmp
livecd gentoo # mount /dev/vg/var /mnt/gentoo/var
livecd gentoo # mkdir usr/portage var/tmp
livecd gentoo # mount /dev/vg/vartmp /mnt/gentoo/var/tmp
livecd gentoo # mount /dev/vg/portage /mnt/gentoo/usr/portage
livecd gentoo # mkdir usr/portage/distfiles
livecd gentoo # mount /dev/vg/distfiles /mnt/gentoo/usr/portage/distfiles

(Set proper perms on tmp directories)
livecd gentoo # chmod 1777 /mnt/gentoo/tmp /mnt/gentoo/var/tmp

Setting Up The Stage

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

Code Listing 2.14: 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 stage from one of our mirrors. Go to /mnt/gentoo and unpack the stage using tar xjpf <stage3 tarball>.

Code Listing 2.15: Download a stage3 archive

livecd gentoo # links http://www.gentoo.org/main/en/mirrors.xml
(Pick a mirror, move to the releases/x86/2008.0/stages/ directory, highlight the
stage3 of your choice, probably the i686 stage3 and press D to download it)

(Or download it directly with wget without choosing a nearby mirror)
livecd gentoo # wget http://distfiles.gentoo.org/releases/x86/2008.0/stages/stage3-i686-2008.0.tar.bz2

Code Listing 2.16: Unpack the stage3 archive

livecd gentoo # time tar xjpf stage3*

real  1m14.157s
user  1m2.920s
sys   0m7.530s

Install the latest Portage snapshot. Proceed as for the stage3 archive: choose a nearby mirror from our list, download the latest snapshot and unpack it.

Code Listing 2.17: Download the latest Portage snapshot

livecd gentoo # cd /mnt/gentoo/usr
livecd usr # links http://www.gentoo.org/main/en/mirrors.xml
(Pick a mirror, move to the snapshots/ directory,
highlight portage-latest.tar.bz2 and press D to download it)

(Or download it directly with wget without choosing a nearby mirror)
livecd gentoo # cd /mnt/gentoo/usr
livecd usr # wget http://distfiles.gentoo.org/snapshots/portage-latest.tar.bz2

Code Listing 2.18: Unpack the Portage snapshot

livecd usr # time tar xjf portage-lat*

real  0m40.523s
user  0m28.280s
sys   0m8.240s

Chrooting

Mount the /proc file system, copy over the /etc/resolv.conf file, then chroot into your Gentoo environment.

Code Listing 2.19: Chroot

livecd usr # cd /
livecd / # mount -t proc proc /mnt/gentoo/proc
livecd / # cp -L /etc/resolv.conf /mnt/gentoo/etc/
livecd / # chroot /mnt/gentoo /bin/bash
livecd / # env-update && source /etc/profile
>>> Regenerating /etc/ld.so.cache...

Set your time zone

Set your time zone information by using the correct listing in /usr/share/zoneinfo.

Code Listing 2.20: Setting your timezone

livecd / # ls /usr/share/zoneinfo
(Using Brussels as an example)
livecd / # cp /usr/share/zoneinfo/Europe/Brussels /etc/localtime

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

Set your host name and domain name

Set your host name in /etc/conf.d/hostname and /etc/hosts. In the following example, we use mybox as host name and at.myplace as domain name. You can either edit the config files with nano or use the following commands:

Code Listing 2.21: Set host and domain name

livecd / # cd /etc
livecd etc # echo "127.0.0.1 mybox.at.myplace mybox localhost" > hosts
livecd etc # sed -i -e 's/HOSTNAME.*/HOSTNAME="mybox"/' conf.d/hostname
(Use defined host name and check)
livecd etc # hostname mybox
livecd etc # hostname -f
mybox.at.myplace

Kernel Configuration

Install a kernel source (usually gentoo-sources), configure it, compile it and copy the arch/i386/boot/bzImage file to /boot.

Code Listing 2.22: Install a kernel source, compile it and install the kernel

livecd etc # time emerge gentoo-sources

real  3m3.110s
user  1m2.320s
sys   0m34.990s
livecd etc # cd /usr/src/linux
livecd linux # make menuconfig

(Configure your kernel as usual and make sure the raid and lvm modules you need are
compiled in, i.e. not as modules. The same applies to the disk drivers and filesystems.)
Multi-device support (RAID and LVM)  --->
[*] Multiple devices driver support (RAID and LVM)
  <*>   RAID support
  < >     Linear (append) mode (NEW)
  <*>     RAID-0 (striping) mode
  <*>     RAID-1 (mirroring) mode
  < >     RAID-10 (mirrored striping) mode (EXPERIMENTAL) (NEW)
  < >     RAID-4/RAID-5 mode (NEW)
  < >     RAID-6 mode (NEW)
  < >     Multipath I/O support (NEW)
  < >     Faulty test module for MD (NEW)
  <*>   Device mapper support
  < >     Crypt target support (NEW)
  < >     Snapshot target (EXPERIMENTAL) (NEW)
  < >     Mirror target (EXPERIMENTAL) (NEW)
  < >     Zero target (EXPERIMENTAL) (NEW)
  < >     Multipath target (EXPERIMENTAL) (NEW)
  < >     Bad Block Relocation Device Target (EXPERIMENTAL) (NEW)

livecd linux # time make -j2

(Elapsed time depends highly on the options you selected)
real  5m5.869s
user  4m32.320s
sys   0m32.930s

livecd linux # make modules_install
livecd linux # cp arch/i386/boot/bzImage /boot/kernel

Configure the system

Edit your /etc/fstab and replace BOOT, ROOT and SWAP with the actual partition names and add your logical volumes. Don't forget to check that the file systems match your installation.

Code Listing 2.23: Example fstab

livecd linux # cd /etc
livecd etc # nano -w fstab
/dev/md1          /boot                   ext2  noauto,noatime  1 2
/dev/md3          /                       ext3  noatime         0 1
/dev/sda2         none                    swap  sw,pri=1        0 0
/dev/sdb2         none                    swap  sw,pri=1        0 0
/dev/vg/usr       /usr                    ext3  noatime         1 2
/dev/vg/portage   /usr/portage            ext2  noatime         1 2
/dev/vg/distfiles /usr/portage/distfiles  ext2  noatime         1 2
/dev/vg/home      /home                   ext3  noatime         1 2
/dev/vg/opt       /opt                    ext3  noatime         1 2
/dev/vg/tmp       /tmp                    ext2  noatime         1 2
/dev/vg/var       /var                    ext3  noatime         1 2
/dev/vg/vartmp    /var/tmp                ext2  noatime         1 2

Configure your network in /etc/conf.d/net. Add the net.eth0 init script to the default run level. If you have multiple NICs, symlink them to the net.eth0 init script and add them to the default run level as well. Either edit /etc/conf.d/net with nano or use the following commands:

Code Listing 2.24: Configure networking

livecd etc # cd 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
(If you compiled your network card driver as a module,
add it to /etc/modules.autoload.d/kernel-2.6)
livecd conf.d # echo r8169 >> /etc/modules.autoload.d/kernel-2.6
(If you want to reconnect via ssh after you have rebooted your new box)
livecd conf.d # rc-update add sshd default

Note: Emerge pcmciautils if you need support for PCMCIA cards.

Set the root password using passwd.

Code Listing 2.25: Set the root password

livecd conf.d # passwd
New UNIX password: type_the_password
Retype new UNIX password: type_the_password_again
passwd: password updated successfully

Edit /etc/conf.d/clock to define the time zone you used previously.

Code Listing 2.26: Edit /etc/conf.d/clock

livecd conf.d # nano -w /etc/conf.d/clock
TIMEZONE="Europe/Brussels"

Check the system configuration in /etc/rc.conf, /etc/conf.d/rc, /etc/conf.d/keymaps and edit any of those files if required.

Code Listing 2.27: Optional: edit some config files

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

Installing System Tools

Install RAID and LVM2 utilities.

Code Listing 2.28: Install RAID & LVM2 tools

livecd conf.d # emerge mdadm lvm2

Install a system logger like syslog-ng and a cron daemon like vixie-cron, and add them to the default run level.

Note: Cron daemons depend on an MTA. mail-mta/ssmtp will be pulled in as a dependency. If you want to use a more advanced 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.

Code Listing 2.29: Install a syslogger and a cron daemon

livecd conf.d # time emerge syslog-ng vixie-cron

real  1m54.099s
user  1m2.630s
sys   0m34.620s
livecd conf.d # rc-update add syslog-ng default
livecd conf.d # rc-update add vixie-cron default

Install the necessary file system tools (xfsprogs, reiserfsprogs or jfsutils) and networking tools (dhcpcd or ppp) if you need any.

Code Listing 2.30: Install extra tools if required

livecd conf.d # emerge xfsprogs       (If you use the XFS file system)
livecd conf.d # emerge jfsutils       (If you use the JFS file system)
livecd conf.d # emerge reiserfsprogs  (If you use the Reiser file system)
livecd conf.d # emerge dhcpcd         (If you need a DHCP client)
livecd conf.d # emerge ppp            (If you need PPPoE ADSL connectivity)

Configuring the Bootloader

Emerge grub and configure it.

Code Listing 2.31: Emerge grub and edit its configuration file

livecd conf.d # time emerge grub

real  1m4.634s
user  0m39.460s
sys   0m15.280s
livecd conf.d # nano -w /boot/grub/grub.conf

Code Listing 2.32: Example grub.conf

default 0
timeout 10

title Gentoo
root (hd0,0)
kernel /boot/kernel root=/dev/md3

Code Listing 2.33: Install grub on both disks

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> root (hd1,0)
 Filesystem type is ext2fs, partition type 0xfd

grub> setup (hd1)

grub> quit

Reboot

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

Code Listing 2.34: Reboot

livecd conf.d # exit
livecd / # umount /mnt/gentoo/usr/portage/distfiles /mnt/gentoo/usr/portage /mnt/gentoo/usr
livecd / # umount /mnt/gentoo/var/tmp /mnt/gentoo/tmp /mnt/gentoo/var /mnt/gentoo/opt
livecd / # umount /mnt/gentoo/proc /mnt/gentoo/home /mnt/gentoo/boot /mnt/gentoo
livecd / # reboot
(Don't forget to remove the CD)

Finalizing the Installation

Note: The total elapsed time between the display of the boot prompt on the minimal CD and the display of the login prompt after the reboot was 00:42:31 on our test box. Yes, less than one hour! Note that this time also includes the stage3, Portage snapshot and several packages download time and the time spent configuring the kernel.

Code Listing 2.35: Connect to your new box from another 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

Code Listing 2.36: Add a new user

mybox ~ # adduser -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

Last configuration touches

Start by selecting nearby mirrors either by defining the SYNC and GENTOO_MIRRORS variables in /etc/make.conf or by using mirrorselect. You can also define the number of concurrent compilation processes at this point.

Code Listing 2.37: Use mirrorselect and set MAKEOPTS

mybox ~ # emerge mirrorselect
mybox ~ # mirrorselect -i -o >> /etc/make.conf
mybox ~ # mirrorselect -i -r -o >> /etc/make.conf
(Usually, (the number of processors + 1) is a good value)
mybox ~ # echo 'MAKEOPTS="-j2"' >> /etc/make.conf

Now is a good time to enable or disable some USE flags. Run emerge -vpe world to list all currently installed packages and their enabled and disabled USE flags. Either edit /etc/make.conf or use the following command to define the USE variable:

Code Listing 2.38: 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 ipv6 and fortran, and enable unicode)
mybox ~ # echo 'USE="nptl nptlonly -ipv6 -fortran unicode"' >> /etc/make.conf

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

Code Listing 2.39: Define locales

mybox ~ # cd /etc
mybox etc # nano -w 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. It is recommended to specify the processor type in the march option and stick to -O2 -pipe.

You may also want to switch to ~x86. You should only do this if you can deal with the odd broken ebuild or package. If you'd rather keep your system stable, don't add the ACCEPT_KEYWORDS variable. Adding FEATURES="ccache" is also a good idea.

Code Listing 2.40: Last edit of make.conf

mybox etc # nano -w make.conf
(Set -march to your CPU type in CFLAGS)
CFLAGS="-O2 -march=athlon-xp -pipe"
(Add the following line)
FEATURES="ccache"
(Only add the following if you know what you're doing)
ACCEPT_KEYWORDS="~x86"

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. You can let your system optimise itself gradually over time when new versions of packages are released. However, recompiling is a still good idea from the standpoint of maintaining system consistency. Please see the Gentoo GCC Upgrading Guide for a discussion on the benefits of ensuring a consistently built system and world.

Recompiling only the packages that have already been updated since the release or that are affected by your new USE flags will take enough time. You might also 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.

Code Listing 2.41: Update your packages

(Install ccache)
mybox etc # emerge ccache

(Please note that the switch to ~x86 causes many packages to be upgraded)
mybox etc # emerge -vpuD --newuse 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 # time emerge -vuD --newuse world
(79 packages have been (re)compiled)

real  180m13.276s
user  121m22.905s
sys   36m31.472s

(Remerge libtool to avoid further potential problems)
mybox etc # emerge --oneshot libtool

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

(If perl has been updated, you should run the perl-cleaner script)
mybox etc # time perl-cleaner all
real  1m6.495s
user  0m42.699s
sys   0m10.641s

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

What to do next

Depending on what your new Gentoo machine is supposed to do, you will probably want to install server applications or a desktop system. Just as an example, emerge gnome and emerge kde have been timed on the ~x86 system installed as describe above. Both have been installed from the same starting point.

You should check our documentation index to find out how to install and configure the applications of your choice.

Important: The following is only an example. It is in no way meant as a recommended setup.

Code Listing 2.42: Emerge GNOME

mybox etc # emerge -vp gnome
(Look at the list of packages and their USE flags,
then edit make.conf if required.
mybox etc # nano -w /etc/make.conf
(The following USE flags have been defined)
USE="nptl nptlonly -ipv6 -fortran unicode svg hal dbus \
     -kde -qt3 -qt4 -arts -eds -esd gnome gstreamer gtk firefox"

mybox etc # time emerge gnome
(326 packages have been emerged)

real  520m44.532s
user  339m21.144s
sys   146m22.337s

Code Listing 2.43: Emerge KDE

mybox etc # emerge -vp kde-meta
(Look at the list of packages and their USE flags,
then edit make.conf if required.
mybox etc # nano -w /etc/make.conf
The following USE flags have been defined)
USE="nptl nptlonly -ipv6 -fortran unicode svg hal dbus \
     kde qt3 qt4 -arts -eds -esd -gnome -gstreamer -gtk -firefox"

mybox etc # time emerge kde-meta
(391 packages have been emerged)

real  1171m25.318s
user  851m26.393s
sys   281m45.629s

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.

Updated November 1, 2008

Summary: The Quick install guide covers the Gentoo install process in a non-verbose manner. Its purpose is to allow users to perform a stage3 install with software RAID and LVM2 in no time. Users should already have prior experience with installing Gentoo Linux if they want to follow this guide.

Xavier Neys
Author

Sven Vermeulen
Author

Steven Wagner
Author

Donate to support our development efforts.