date # Check the date. date MMDDhhmmYYYY # Change if needed.
Gentoo is one of the most Linuxy Linux distributions. That is to say if you like the things that make Linux what it is, you'll probably like Gentoo. When I was installing Gentoo the first few times, I had the feeling that the procedure could be wrapped up in a script… Yes indeed, they call that Slackware. If the procedure is simplified and automated, then you will inevitability suffer a limitation of possibilities. Gentoo tries hard to avoid the least common denominator effect by making you do everything explicitly. Realizing this, I thought that perhaps a more flexible script could be written to just prompt you as to what to do next. Then I realized that I had incidentally written such a script on a piece of paper in the form of these notes. So imagine that you're being prompted by each item on this procedure in order without any limitations on your ability to do whatever you want in the ordinary Linux way.
Gentoo is filled with delightful idiosyncracies. To use Gentoo, you really have to know what you're doing. Fortunately, since that's a requirement by design, there is a lot of excellent help out there. And because knowing what's going on is a requirement, the organization of the distribution is as unobfuscated as possible. For example, in any Linux distribution, you will eventually have to make configuration changes by editing some configuration file; given this fact, isn't it reasonable to say that all configuration changes should be made in this way?
The first step is to generally know what you're doing when you see a Unix command prompt. If the whole idea of a command prompt makes you feel like your choices are limited, then Gentoo may not offer much advantage to you. If you realize that a command line gives you all the power you could possibly have, then Gentoo will seem very clever and elegant. For example, when installing other distributions (SuSE for example), I sometimes use CTR-ALT-F2 to get to a text console to see if I can find out the cause of any problems I'm having. Gentoo makes that the default mode. The Gentoo philosophy is to not protect the user from the ability to solve problems.
Pro
Excellent on-line help.
Managed cusomizability of packages.
Great for minimal istallations, secialty servers, etc.
Biggest collection of packages, i.e. biggest collection of software.
Ability to use experimental/development software is designed in.
Can be installed completely remotely! No boot disks needed.
You can use the system while installing.
Only have what you need/want.
Staying up to date is extremely easy. It can be automated for everything or specific packages.
Generally fast rebooting compared to other OSs.
Generally faster performance compared to other OSs.
Eliminates problems with non-native libraries.
Good support for non traditional chip architectures.
Makes it possible to better understand what is going on behind the scenes.
Compiling/installation is a good stress test before deploying a machine.
Nice text console organization. For example, excellent use of color.
Solves problem of how to upgrade a machine that must remain in service during the upgrade (perhaps with a different Linux).
System administration does not depend on fragile GUI tools.
Con
Obviously compiling an entire OS takes a while.
Fragmented disks from lots of compiling (in /var/tmp).
etc-update is not popular or fun… Investigate cfg-update.
Important messages get lost in a sea of non important compiler messages or zoom off the screen.
I've had various versions of Gentoo install disks totally hang during hardware detection on various machines. I usually am now prepared with a sysresccd and older install disks. One of those will work.
nano. I hate this idiotic editor. Gentoo is optimized for people who know what they're doing - except for their choice of editor.
Before you begin, you will need a computer and a way for that computer to get and store data. Really, that's all that is strictly required. Ideally you want a CDROM reading ability and a connection to the Internet, though you can do without either. The most obvious way to get started is to get a Gentoo install CD image and burn it onto a CD and boot from that. But let's say you don't have a CD burner. That's a problem, but unlike with other distributions (and certainly OS's), that problem is not insurmountable.
One of the nice things about Gentoo is that it can be completely installed while running another OS. So from a working Red Hat system, you can install Gentoo on another partition or drive. In this case, no installation CD is necessary at all. Of course the data has to come from somewhere and if you don't have it on a CD, it must come from a network (or filesystem, etc).
The Gentoo installation CD is basically a fancy boot disk optimized by including all the handy tools you could possibly want to have access to while you handcraft your operating system. The emphasis of this CD is booting a working Linux system that has tons of handy tools and, just as importantly, a working network connection, if possible. Usually, the boot disk will autodetect your NIC hardware and automatically use DHCP and be ready for action without doing anything. If your installation is more difficult, oh well, at least you have the full power of Linux and it's tools to dig yourself out of that hole.
I find that the rescue disk known as sysresccd is a great tool for all kinds of Linux jobs. I always like to have one lying around. This disk has been very effective for me as a substitute for the real Gentoo install disks. Another trick I would propose that really leverages the power of Gentoo is remote installation. Despite the fact that such a highly customizable distribution needs a lot of customization, you can minimize the impact of this by doing the install completely remotely. If you can log into a computer somewhere (as root), there is a good chance you can do the entire installation procedure from afar. So with the sysresccd or the Gentoo bootdisks, sshd is included and you can fire that up and then go back to your real computer to finish the whole job. If you aren't following what I'm saying here, don't worry, it's just an advanced way to exploit the Gentoo concept.
Set the date if needed. This helps minimize confusion with package freshness.
date # Check the date. date MMDDhhmmYYYY # Change if needed.
Optional: It's sometimes useful to not let the screen blank so you can keep a casual eye on the compiling processes. This is only necessary if you're going to be installing at the console (in the ordinary way).
setterm -blank 0
Optional: If you want to do the entire installation from somewhere else, just start the ssh server. The default password is randomly chosen so you must reset it.
passwd /etc/init.d/sshd start
The screen program allows some great tricks. First, with it, you can be doing one installation on one virtual terminal while looking at these notes on another. Ultimately, when you know what you're doing, you can be working on two or more parts of the installation process at the same time. The advantage of this over just using the native Linux consoles (Alt-Fn) is that these vitual terminals can be switched when working remotely. The other immensely helpful thing screen does is that it allows you to start a big compile and then close that terminal. This is nice if you don't want to leave a compile running on a public terminal or one that you want to use for other purposes. The "nohup" command can do this too, but screen is much better since with it you can bring sessions back to the foreground. This is most useful when, for example, starting an install at one location and then going to another to finish it.
screen -e^gg # Where ctrl-g is my favorite escape key.
Partition the drives.
fdisk /dev/sda
Or whatever your drive/s is/are. Use dmesg | less to search for more complicated drive naming schemes like /dev/cciss/disc1/disc.
Set up a boot partition (this is optional and sometimes I find it to be more trouble than it's worth). Best to make this ext2.
mkfs.ext2 /dev/sda1
Format the main drive or drives.
mkfs.ext3 /dev/sda2
Or mkfs.reiserfs is a good chioce too. Or use some formatted drives that are already full of Linux stuff. Do what you have to do. It's your choice.
Format the swap space.
mkswap /dev/sda4
Why not utilize that swap space right now?
swapon /dev/sda4
Gentoo disks tend to have this mount point. Mount main system's drive.
mount -t ext3 /dev/sda2 /mnt/gentoo
Now that you've prepared the place this Gentoo installation will live, it is time to actually install Gentoo itself. There are a few ways to do this, but the easiest way for me is to unpack a big compressed tar file containing the main skeleton of the entire system. Gentoo has a notion of "stages". If you're reading these instructions, you definitely want stage 3 which will include a few precompiled utilities in the skeleton (a compiled compiler, software for getting more software, etc) which will help get the ball rolling.
This stage 3 file is found on "Universal" Gentoo install disks. I tend to use "Minimal" install disks so I have to scrounge the web for them. Since you probably will be installing software from the Internet anyway, it's not a bad scheme. If you don't already have a stage 3 tar file, open a new screen terminal and run Twibright Links to look for a mirror (links google.html). Enter a search term like site:edu ftp mirror gentoo stages bz2. That should get you close You can download it with Twibright Links (press d), or:
wget ftp://mirror.usu.edu/mirrors/gentoo/releases/x86/current/stages/stage3-x86-2006.0.tar.bz2
Note that with some install CDs you might not have room to install it into the system directories. You may need to cd into the target volume. It's ok for the tar file to be there in what will be the top / directory.
It's very little trouble to see if the download went well. Consider it insurance:
wget ftp://mirror.usu.edu/mirrors/gentoo/releases/x86/current/stages/stage3-x86-2006.0.tar.bz2.DIGESTS md5sum stage3-x86-2006.0.tar.bz2.DIGESTS cat stage3-x86-2006.0.tar.bz2 # Do they look the same?
Once you have the tar file in place where it can be used, upack it. This shows how it might be done if you didn't have to go find a tar file, but were able to use one from a "Universal" installation CD.
time tar -xjpf /mnt/cdrom/stages/stage3-i686-2004.3.tar.bz2 -C /mnt/gentoo
Add a "-v" to watch the action (this is slower).
Assuming there is a boot partition.
mount -t ext2 /dev/sda1 /mnt/gentoo/boot
This should be done in preparation for switching to the new filesystem.
mount -t proc none /mnt/gentoo/proc
Since you know the network works at this point and you can access both the installation filesystem and the new Gentoo one, go ahead and copy your DNS.
cp -L /etc/resolv.conf /mnt/gentoo/etc
You need to tell the Gentoo installer where it should be getting software from. There is a utility called mirrorselect. I used to use it, but once you've used it a couple of times, you can just keep using the same configuration (assuming you stay roughly in the same geographic place).
This takes ages!! (and it's optional!)
mirrorselect -a -s4 -o >> /mnt/gentoo/etc/make.conf
Or pick'em yo'self (quick!)
mirrorselect -i -o >> /mnt/gentoo/etc/make.conf
You can also do a :r!mirrorselect -i in vim while editing make.conf and choose some more (USA) by hand.
These days I just copy a make.conf from a known good system and then edit it. If you don't have that established yet, just follow the hints in the /mnt/gentoo/etc/make.conf.example file.
scp xed@$XED:/etc/make.conf /mnt/gentoo/etc
This shows what kind of processor you're working with which might come in handy when picking compile flags. Check out this list of safe cflags for a good idea of what to put here.
cat /proc/cpuinfo vim /mnt/gentoo/etc/make.conf
Set mountpoints for your drives.
vim /mnt/gentoo/etc/fstab
Something like this is typical:
/dev/sda2 / ext3 noatime 0 1 /dev/sda3 /data ext3 noatime 0 1 /dev/sda4 none swap sw 0 0 /dev/sdd1 /mnt/usbmem vfat noauto 0 0 /dev/cdroms/cdrom0 /mnt/cdrom iso9660 noauto,ro 0 0 proc /proc proc defaults 0 0 shm /dev/shm tmpfs nodev,nosuid,noexec 0 0
This trick changes the current filesystem to be limited to (root changed) the file system the new Gentoo installation will use.
chroot /mnt/gentoo /bin/bash
Now the system behaves a lot like the new installation will.
Pick the right one obviously. Then check that date again!
ln -sf /usr/share/zoneinfo/America/Los_Angeles /etc/localtime date date MMDDhhmmYYYY.ss
Further makes the system like it will eventually be.
env-update; source /etc/profile
Double check that network is up and good. (Try using ssh or wget to test if firewall doesn't allow ping (ICMP).
ifconfig; ping www.gentoo.org -c3
This creates the "portage" database. This is a complete list of what is available and how it needs to be installed. Notice that I preface most of these commands with the time command because I like to know how long all this takes.
time emerge --sync
The emerge command is part of the portage system. If there is an update to the portage system itself (since the version on the install disk - this is very likely), it is very wise to update the updater first thing.
time emerge portage
Emerging typically downloads the source, compiles it, and puts it in the filesystem. Start by emerging the entire core system and kernel source. (If you know what you're doing, you can go to kernel.org and get your own kernel source.)
time bash -c 'emerge system && emerge gentoo-sources genkernel'
If you're installing on a slow machine, go to bed. Let sit overnight. Newer (dual Opteron, for example) machines can do this in a few hours.
I used to compile my kernel at this point, but now I usually kick off a long list of packages to install and the switch screens and work on the kernel configuration concurrently. I sometimes find on simple systems that the packages can all be installed by the time I've finished setting all the kernel options.
The technique to install packages basically uses the emerge command like this:
emerge app-editors/vim --pretend --verbose emerge vim -pv # You don't really need the category unless there's a clash. # Maybe make some adjustments here to "USE=" in /etc/make.conf time emerge vim emerge tree pinfo losf atop -av # You can install many at once.
The -a is for —ask and is like a —pretend except that you are prompted to actually go for it or cancel. It's pretty much always a good idea to use either -av or -pv when emerging stuff because it often shows you interesting things that your getting that you may not have wanted or compile options that are turned off that you actually would appreciate. To make temporary changes in compile options, you can do something like this:
USE="-gnome kde" emerge ethereal USE="tcltk" emerge python
It's better to set these directives specifically by including them in the USE definition of the /etc/make.conf file.
If you don't know the name of a package you think exists, you can try something like:
emerge -s john # Which finds package: johntheripper
You can also poke around in /usr/portage/*/ and see what you might like.
The thing to do now is find a bunch of packages you want and start them with a big emerge. Then switch over to another console and work on your kernel.
Actually, some of these packages I merely tolerate.
app-portage/gentoolkit
sys-kernel/gentoo-sources
sys-kernel/genkernel
app-portage/ufed
sys-apps/coldplug
sys-apps/hotplug
app-editors/vim
app-misc/screen
mail-client/mutt
net-ftp/lftp
app-text/tree
app-text/pinfo
sys-process/lsof
sys-process/atop
sys-boot/grub
net-misc/dhcpcd
net-firewall/iptables
sys-apps/eject
net-misc/openssh
app-text/rcs
dev-util/cvs
net-fs/nfs-utils
app-admin/metalog
mail-mta/ssmtp
sys-process/vixie-cron
sys-process/at
net-misc/ntp
net-www/apache
app-text/asciidoc
app-text/tetex
app-text/antiword
net-misc/whois
net-analyzer/iptraf
net-analyzer/hping
net-analyzer/tcpdump
net-analyzer/nmap
net-dns/bind-tools
net-analyzer/traceroute
net-analyzer/netcat
net-analyzer/wireshark
app-crypt/johntheripper
app-admin/tripwire
dev-db/pygresql
dev-python/sqlobject
dev-db/pgadmin3
dev-db/mysql
dev-python/mysql-python
app-arch/gzip
app-crypt/gnupg
app-crypt/ccrypt
www-client/links
www-client/lynx
www-client/mozilla-firefox
net-im/centericq
dev-lang/php
dev-java/blackdown-jdk
dev-java/blackdown-jre
dev-lang/tcl
dev-python/ipython
app-text/ghostscript-esp NEEDS X
app-text/a2ps NEEDS ghostscript-esp, X
x11-base/xorg-x11
x11-terms/aterm
x11-wm/ratpoison
x11-wm/blackbox
x11-misc/bbkeys
media-gfx/xv
media-gfx/inkscape
media-gfx/gimp
app-text/xpdf
app-text/gv
sci-visualization/gnuplot
www-client/mozilla-firefox
media-gfx/imagemagick
media-video/mplayer
media-gfx/gphoto2
media-gfx/jhead
media-sound/alsa-utils
media-sound/alsa-tools
app-cdr/cdrtools
media-sound/sox
media-sound/mpg123
media-sound/alsaplayer
media-sound/abcde
media-sound/mp3blaster
Hopefully you have some kernel source. If you need to find out about your hardware, the kernel messages might be helpful.
<ALT-F2> dmesg | less; <ALT-F3> lspci
Now you need to compile your kernel. This requires lots of attention to do properly. Gentoo provides a script to help install everything nicely in the Gentoo context.
genkernel --debuglevel=5 --color --menuconfig all
You still have to know what you're doing with make menuconfig. Because you have to know how to compile a kernel, it's really not much of a big deal to get your own kernel sources and compile it in your own favorite way.
Prepare servers and system daemons you wish to have running on this system. Customize this list to suit your needs. Nothing is critical here since you can add these later when you realize your running system is missing them.
SERVS="sshd vixie-cron net apache2 alsasound atd metalog net.eth0 ntpd" for X in $SERVS; do rc-update add $X default; done
Change the "EDITOR" variable in /etc/rc.conf to vim.
emerge --unmerge nano
Double check your bootloader's configuration. In simple cases it may be ok.
vim /boot/grub/grub.conf
If this doesn't exist, import :r /boot/grub/grub.conf.sample from vim.
Install the bootloader using the grub shell.
# grub --no-floppy grub> root (hd0,0) grub> setup (hd0) grub> quit
Or you can install the bootloader using grub's install script.
grub-install --no-floppy /dev/sda
The root password is auto scrambled. The root password must be reset!
passwd
If you just want the only NIC to use DHCP, don't do anything since that is the default behavior. Otherwise networking settings go here:
vi /etc/conf.d/net
An easy configuration looks like this:
iface_eth0=( "10.0.0.44" ) routes_eth0=( "default via 10.0.0.1" ) iface_eth1="dhcp"
Make the network persistent on reboot.
rc-update add net.eth0 default
Get out of the chroot situation.
exit; cd /
Unmount all the drives because that is the nice thing to do.
umount /mnt/gentoo/proc /mnt/gentoo/boot /mnt/gentoo
If you have umounting trouble, i.e. "device is busy" and you know it's not busy, use the -l flag.
You're kind of finished in an abstract way. It's usually a good idea to pull your install CD out of the drive now.
reboot
Since Gentoo can take a long while to install properly, it's often nice to be able to do most of the install work from another machine. In fact, it's a nice feature to be able to sit at your most comfortable workstation and work on installing Gentoo on some machine with a bad keyboard/display in a freezing cold server room. The trick is to set up a ssh daemon.
When starting sshd from sysresccd and other miscellaneous boot/rescue disks, you might need to explicitly set up the keys.
for TYPE in "rsa dsa rsa1"; do ssh-keygen -t $TYPE -f /etc/ssh/ssh_host_$TYPE_key; done
There might be an easier way to do this. With real Gentoo install disks, and maybe others, it's all automatic with:
/etc/init.d/sshd start
Run the ssh server. Don't forget to set a known password!
sshd passwd ssh localhost # Test. Then Ctrl-d.
Test that connections are being accepted. A better test is to log in to the machine you want to work from and see if you can log back into the install machine.
An accurate clock ranges from nice to critically essential. Gentoo has made some changes in the way ntp is used. Basically ntpd has taken over the job of ntp-client. These days, setting up ntp is not very problematic.
Get the ntp software including ntpd and utilities.
emerge ntp
Add NTPCLIENT_OPTS. I use ntp.ucsd.edu (132.239.1.6). This is probably only necessary if you want to get fussy about which time server you use. You've made it this far with Gentoo - of course you're fussy!
vim /etc/conf.d/ntp-client
Start the client now.
/etc/init.d/ntp-client start
Set ntp to run at boot. Repeat this process for ntpd.
rc-update add ntpd default
The very concept of the caplock key is aggravating to me. Obviously such a useless function should not have its own key and certainly not a key so easy to type. Once you get used to having a control key just to the left of the "A", your arthritis will be cured, you'll be able to bowl a perfect game, your life will be a joyous celebration, and you will no longer be able to use uncorrected keyboards.
The way to really deeply cure caplockitis is to edit the keyboard mappings.
vi /usr/share/keymaps/i386/qwerty/us.map.gz
Change keycode 58 from "Caps_Lock" to "Control".
Make this take effect.
loadkeys us
Ah, that's better.
For those people who use graphics, it's pretty easy to fix.
vi /etc/X11/xorg.conf
Enable Option "XkbOptions" "ctrl:nocaps".
At anytime you can update your system so that it is taking advantage of the latest stable versions of everything you use. That is a Gentoo perk. Every once in a while Gentoo comes out with a new "profile", for example, 2004.3 changes to 2005.1, etc. What exactly this means is more subtle than with distributions that use distribution mumbers to imply a set of programs frozen at some particular version. A Gentoo profile tends to affect the default way things are organized and things like which version of portage is recommended. The practical effects of a new profile are often not all that serious, however, it's a nice idea to update when you can. Fortunately it's very easy.
This symlink is how the current profile for the system is defined. If you want your system to behave like another version, this is where you set that.
ln --no-dereference -sf ../usr/portage/profiles/default-linux/x86/2005.1 /etc/make.profile emerge --sync # Sync the portage database. emerge portage # Update portage if needed. emerge -uD world
Update everything. The -u is update, the -D is look deep into dependencies, and world is all of the stuff you have currently installed. You might want to do a -pv to preview the changes that will be made and see if you have a problem with anything. Also, previewing will give you an idea of how long the update might take. It can take quite a while.
After the upgrade, you can update any configuration files that may have been affected. This is probably a good idea. This allows you to incorporate new config files for various reinstalled items. This can be critically necessary to make new versions work, but it can also wipe out things that you've customized (like a web server config file, for example). So follow instructions and watch what you're doing.
etc-update
There's a reason why Richard Stallman calls them Nvidious. If you use an Nvidia graphics card, better run your special driver installer again. If you don't or don't care about 3d, don't worry about it.
sh NVIDIA.....
Want to have a look at your USE flag options? Try this:
cat /usr/portage/profiles/use.* | less
Or if you're really serious about USE flags, Gentoo has a very compact utility to understand and edit them.
emerge ufed ufed
Some USE flags I like to consider:
imap - Especially helpful with mutt.
svg - Scalable Vector Graphics, generally a "Good Thing".
opengl - If you want graphics, you might want 3d graphics
-X - For text only machines.
alsa -oss - Try to convince software to do sound the new Linux way.
ogg - The righteous codec.
verbose - As if the build process didn't output enough junk.
x86 - For normal machines.
amd64 - For fancy machines (other fancy machines are available).
ldap - For use on fancy systems run by fancy admins.
sse sse2 - Floating point optimizations (see /proc/cpuinfo)
nvidia - For Nvidious displays.
Sometimes when you do an emerge it complains that something is "blocked" by something else. This means that by installing whatever it is you want to install, you will clobber or otherwise conflict with something already in place. Often this happens indirectly with system related dependencies that you have very little understanding of. The general solution is to delete the blocking package and try again. The way you delete is by using emerge —unmerge. Here's an example that happened when the basic organization of how authentication was changed:
# emerge -uD world -av # Note that "shadow" is blocked. !!! Error: the sys-apps/pam-login package conflicts with another package; # emerge --unmerge sys-apps/pam-login # emerge shadow -av # Put this facility back right now. # emerge -uD world -av # Continue. Should be good.
USE='imap' emerge mutt
# vi ~/.muttrc
set sendmail="/usr/sbin/ssmtp"
# vi /etc/ssmtp/ssmtp.conf
mailhub=smtp.west.cox.net
rewriteDomain=xed.ch
emerge apache2
# vi /etc/apache2/httpd.conf
Listen 8000 # <- Change port (to get around ISP's "service")
ServerAdmin webmaster@correctemail.ch
# vi /etc/conf.d/apache2
APACHE2_OPTS="-D USERDIR"
# rc-update add apache2 default
# /etc/init.d/apache2 [start|restart]
# emerge xorg-x11 bbconf bbkeys bbdate # env-update; source /etc/profile # Generate a /etc/X11/xorg.conf file. # Xorg -configure # xorgconfig (tweak settings) -- Proview 766s 1280x1024 (75Hz|,80kHz-) -- 3Dfx Banshee 16384kb Ram # emerge blackbox; emerge bbkeys
emerge alsa-lib alsa-utils mpg123 rc-update add alsasound boot # This does important things alsamixer # unmute what you need and set your levels alsactl store # Save current mixer settings /etc/init.d/alsasound start # Start it now too.
Enabling users to use the su command and sound. Add user xed to wheel and audio group:
gpasswd -a xed wheel audio
Or just edit the group file:
wheel::10:root,xed audio::18:xed