This is derived from official Gentoo documentation resources (the Gentoo Handbook and especially the Gentoo Linux x86 Quick Install Guide).
Download a CD or DVD ISO image from my personal mirror ( x86 or amd64 ) or from one of the official Gentoo mirrors. The ISO images are found on the official mirrors in releases/arch/current-iso (that is, for x86, the path would be releases/x86/current-iso).
In any case, this directory also includes the stage3 image(s) for that architecture as well.
Burn the image to a CD or DVD and boot it on the target machine.
This is the most reliable way to get a build environment for Gentoo (in most cases, dummy, remember when you had to build a custom kernel to get to a prompt?). If this doesn't work, then go to the Gentoo Handbook for information and links that will guide you through the more difficult installations.
If the hardware is not going to cause you any problems, you can just press ENTER to boot the frame buffer based Gentoo kernel. If that doesn't work, press F2 at the boot screen to find out what boot options exist. A good second try is to boot to the gentoo-nofb kernel which disables the framebuffer. And if all goes well, the hardware will be detected and the modules will be loaded. If that kernel fails to boot properly or hangs up, you need to read the Gentoo Handbook or Quick Start Guide. In fact, if anything deviates from a perfect install, go look at the documentation! Sorry,...
In most cases the network will be up and running if you have a wired Ethernet connection. Verify this by entering the command ifconfig eth0. Or enter the command ifconfig if that doesn't work. It should report a valid Ethernet IP address (something like 192.168.0.13, for example). If the network is not configured already, use net-setup to configure it. Remember, you might need to load support for a network card using modprobe prior to configuration. And, of course, if this is not enough information, go back to the official documentation.
For wireless access, use iwconfig to set the wireless parameters and then use either net-setup again or run ifconfig, dhcpcd and/or route manually.
If you are behind a proxy, do not forget to initialize your system configuration using
livecd root # export http_proxy livecd root # ftp_proxy livecd root # RSYNC_PROXY
Alternatively, start networking manually. The following example assigns the IP address 192.168.1.10 to the new PC and defines 192.168.1.1 as the router and the name server.
livecd root # ifconfig eth0 192.168.1.10/24 livecd root # route add default gw 192.168.1.1 livecd root # echo nameserver 192.168.1.1 > /etc/resolv.conf
Now for us lazy guys who want to scroll back and look at stuff we've forgotten in the last 30 minutes. We can then log into the new system over an ssh link. Then you can work with one of those new-fangled graphics windowing environments.
First, set the root password on the booted minimal or live CD so that we can connect to it from another PC. [Repeating the Gentoo docs advice: please note that allowing root to connect over ssh is not recommended under normal circumstances. If you can't trust your local network, use a long and complex password. I will use it only once as it disappears after the install is complete, that is, on the first reboot.]
Set the root password |
livecd root # passwd New UNIX password: type_a_password Retype new UNIX password: type_a_password passwd: password updated successfully |
Now, start a terminal window on the other PC and connect to the new box, scroll to your hearts content, and cut and paste commands with wild abandon.
Connect to the new box from another PC |
(Use the IP address of your new box) $ ssh root@192.168.1.10 The authenticity of host '192.168.1.10 (192.168.1.10)' can't be established. RSA key fingerprint is 96:e7:2d:12:ac:9c:b0:94:90:9f:40:89:b0:45:26:8f. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added '192.168.1.10' (RSA) to the list of known hosts. Password: type_the_password |
Use fdisk or cfdisk to create your partition layout. You need at least one Linux partition (type 83), and in many cases a second and maybe even a third for /boot and /home. In most cases you will want a swap partition (type 82) as well.
The following scenario creates a /boot, a swap and a main partition as used in our handbook. Replace sda with your disk. Depending on the boot loader (grub, installed in the MBR, for example) the bootable flag may be ignored, but in many cases is is required (grub on GPT disks or any time the boot loader is installed in the partition header). Set this flag on the boot partition with fdisk's a command.
Create the partitions (if needed) |
livecd ~ # fdisk /dev/sda (The rest of this guide uses the following partitioning scheme) livecd ~ # fdisk -l /dev/sda Disk /dev/sda: 599.9 GB, 599978409984 bytes 255 heads, 63 sectors/track, 72943 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Device Boot Start End Blocks Id System /dev/sda1 * 1 12 96358+ 83 Linux /dev/sda2 13 110 787185 82 Linux swap / Solaris /dev/sda3 111 72943 585031072+ 83 Linux |
Use mke2fs, mke2fs -j, mkfs.xfs, etc., to create file systems on your Linux partitions. Initialize your swap partition using mkswap and swapon.
Create the file systems and activate the swap |
(ext2 is all you need on the /boot partition) livecd ~ # mke2fs /dev/sda1 (Let's use ext3 on the main partition) livecd ~ # mke2fs -j /dev/sda3 (Create and activate swap) livecd ~ # mkswap /dev/sda2 && swapon /dev/sda2 |
Mount the file systems on /mnt/gentoo. Create directories for the other mount points if you need them (like /mnt/gentoo/boot and /mnt/gentoo/home) and mount them as well.
Mount the file systems |
livecd ~ # mount /dev/sda3 /mnt/gentoo livecd ~ # mkdir /mnt/gentoo/boot livecd ~ # mount /dev/sda1 /mnt/gentoo/boot livecd ~ # cd /mnt/gentoo |
Now make sure your date and time is set correctly using date MMDDhhmmYYYY. Use UTC time.
Set the date and UTC time |
(Check the clock) livecd gentoo # date Mon Mar 6 00:14:13 UTC 2006 (Set the current date and time if required) livecd gentoo # date 030600162006 (Format is MMDDhhmmYYYY) Mon Mar 6 00:16:00 UTC 2006 |
Next, download a stage3 (see the top of this page for the official Gentoo sources, again). You can find it on my mirror in my x86 stage3 directory. And likewise a snapshot of the Portage tree. Then extract the contents of the stage3 tar file to /mnt/gentoo and the contents of the portage tar file to /mnt/gentoo/usr.
Download the stage3 archive |
livecd gentoo # wget http://www.marslett.us/gentoo-distfiles/releases/x86/current-stage3/stage3-i686-*.tar.bz2 livecd gentoo # wget http://www.marslett.us/gentoo-distfiles/snapshots/portage-latest.tar.bz2 livecd gentoo # tar xjpf stage3* livecd gentoo # cd usr livecd gentoo # tar xjpf ../portage*.bz2 |
At this point the new Gentoo installation should be functional (but not bootable). Mount the /proc & /dev file systems, copy over the /etc/resolv.conf file, then chroot into the freshly built Gentoo environment.
Magical CHROOT! |
livecd usr # cd /mnt/gentoo livecd / # mount -t proc proc proc livecd / # mount --rbind /dev dev livecd / # cp -L /etc/resolv.conf etc livecd / # chroot . /bin/bash livecd / # env-update && . /etc/profile >>> Regenerating /etc/ld.so.cache... |
Set the root password, the time zone information, host name and domain name. And edit your /etc/fstab, replacing BOOT, ROOT and SWAP with the actual partition names. Don't forget to check that the file systems specified match the installation.
Setting up the minimum changes to /etc |
(Set the permanent password) livecd / # passwd New UNIX password: type_a_password Retype new UNIX password: type_a_password passwd: password updated successfully (Find the file to copy) livecd / # ls /usr/share/zoneinfo (Using Chicago as an example) livecd / # cp /usr/share/zoneinfo/America/Chicago /etc/localtime livecd / # date Wed Mar 8 00:46:05 CST 2006 (Set the host name - this computer's name) ( Note that the "at.myplace" is the domain: marslett.us here) livecd / # echo "127.0.0.1 mybox.at.myplace mybox localhost" > /etc/hosts livecd / # sed -i -e 's/HOSTNAME.*/HOSTNAME="mybox"/' /etc/conf.d/hostname (Use defined host name and check) livecd / # hostname mybox livecd / # hostname -f mybox.at.myplace livecd / # nano -w /etc/fstab (after editing, this is a reasonable fstab) /dev/sda1 /boot ext2 noauto,noatime 1 2 /dev/sda3 / ext3 noatime 0 1 /dev/sda2 none swap sw 0 0 |
Get ready for the kernel compilation experience! Stage3 has most of what you need to have installed, but you will need genkernel (for building the RAMdisk) and gentoolkit (for things like revdep-rebuild).
Next install a kernel source (gentoo-sources is generally recommended, but git-sources is not that scary), configure it, compile it, install it and if needed, build the RAMdisk image.
Installing the first kernel |
livecd / # emerge genkernel livecd / # emerge gentoolkit livecd / # emerge gentoo-sources livecd / # cd /usr/src/linux livecd linux # make menuconfig (Configure your kernel) livecd linux # make livecd linux # make modules_install livecd linux # make install (If you need kernel modules to boot, build a RAMdisk) livecd linux # genkernel --kerneldir=. ramdisk |
For a static network configuration, configure the network in /etc/conf.d/net. Symlink the net.lo init script to net.eth0 and install it to the default run level. If there are more NICs, do the same for them.
Either edit /etc/conf.d/net with nano or use the following commands:
Configure networking |
livecd linux # cd /etc/init.d livecd init.d # ln -s net.lo net.eth0 livecd init.d # cd /etc/conf.d livecd conf.d # echo 'config_eth0=( "192.168.1.10/24" )' >> net livecd conf.d # echo 'routes_eth0=( "default via 192.168.1.1" )' >> net livecd conf.d # rc-update add net.eth0 default (For network drivers compiled as modules) livecd conf.d # echo r8169 >> /etc/modules.autoload.d/kernel-2.6 (And to allow connecting via ssh after rebooting) livecd conf.d # rc-update add sshd default |
Edit /etc/conf.d/clock to define the time zone you used previously. Otherwse it may go away during a future emerge.
Check the system configuration in /etc/conf.d/rc, /etc/conf.d/keymaps and /etc/rc.conf. Then make any edits required.
Edit some config files as required |
(set the time zone for future updates) livecd conf.d # nano -w clock TIMEZONE="America/Chicago" livecd conf.d # nano -w rc livecd conf.d # nano -w keymaps livecd conf.d # nano -w /etc/rc.conf |
Install a system logger like syslog-ng and a cron daemon like vixie-cron. Then add them to the default run level. And don't forget the file system utilities and network tools.
Note: Cron daemons depend on an MTA. mail-mta/ssmtp will be pulled in as a dependency. If you want to use another MTA, you might want to install it now. If you are in a hurry, let ssmtp be installed and remove it later when you install the MTA of your choice. |
Installing a syslogger and cron daemon |
livecd conf.d # emerge syslog-ng vixie-cron livecd conf.d # rc-update add syslog-ng default livecd conf.d # rc-update add vixie-cron default livecd conf.d # emerge xfsprogs (If you use the XFS file system) livecd conf.d # emerge dhcpcd livecd conf.d # rc-update add dhcpcd default (If you need a DHCP client) livecd conf.d # emerge ppp +(If you need PPPoE ADSL connectivity) |
Emerge grub and configure it.
Emerge grub and edit its configuration file |
livecd conf.d # emerge grub livecd conf.d # nano -w /boot/grub/grub.conf |
Example grub.conf (old style) |
default 0 timeout 10 title Gentoo root (hd0,0) kernel /boot/kernel root=/dev/sda3 initrd /boot/ramdisk.bz2 |
Installing classic grub |
livecd conf.d # grub Probing devices to guess BIOS drives. This may take a long time. grub> root (hd0,0) Filesystem type is ext2fs, partition type 0xfd grub> setup (hd0) Checking if "/boot/grub/stage1" exists... yes Checking if "/boot/grub/stage2" exists... yes Checking if "/boot/grub/e2fs_stage1_5" exists... yes Running "embed /boot/grub/e2fs_stage1_5 (hd0)"... 16 sectors are embedded. succeeded Running "install /boot/grub/stage1 (hd0) (hd0)1+16 p (hd0,0)/boot/grub/stage2 /boot/ grub/menu.lst"... succeeded Done. grub> quit |
Exit the chrooted environment, unmount all file systems and reboot:
And finally reboot |
livecd conf.d # exit livecd / # umount /mnt/gentoo/dev /mnt/gentoo/proc /mnt/gentoo/boot /mnt/gentoo livecd / # reboot (Remove the CD) |
When the system has booted up, log in as root, and add one or more users for daily use with useradd.
Also, remove the ssh information for the former configuration and prepare for ssh usage in the future.
Add a new user |
mybox ~ # useradd -g users -G lp,wheel,audio,cdrom,portage,cron -m john mybox ~ # passwd john New UNIX password: Set John's password Retype new UNIX password: Type John's password again passwd: password updated successfully |
Connect to your new box from another PC |
(On your second PC, clean up your known_hosts file because your new box has generated a new definitive hostkey) $ nano -w ~/.ssh/known_hosts (Look for the IP of your new PC and delete the line, then save the file and exit nano) (Use the IP address of your new box) $ ssh root@192.168.1.10 The authenticity of host '192.168.1.10 (192.168.1.10)' can't be established. RSA key fingerprint is 96:e7:2d:12:ac:9c:b0:94:90:9f:40:89:b0:45:26:8f. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added '192.168.1.10' (RSA) to the list of known hosts. Password: type_the_password |
Define my mirrors and define the number of concurrent compilation processes and the number of parallel emerges that may be run at this point.
My first make.conf |
# These settings are for the first emerges as a new system is moved over to
# Gentoo.
CFLAGS="-O2 -march=native -pipe"
CXXFLAGS="${CFLAGS}"
# MAKEOPTS="-j3"
# EMERGE_DEFAULT_OPTS="--jobs=3"
# WARNING: Changing your CHOST is not something that should be done lightly.
# Please consult http://www.gentoo.org/doc/en/change-chost.xml before changing.
CHOST="i686-pc-linux-gnu"
ACCEPT_LICENSE="*"
#PORTDIR_OVERLAY="/home/cmarslett/my-portage"
#source /var/lib/layman/make.conf
SYNC="rsync://www.marslett.us/gentoo-portage"
GENTOO_MIRRORS="\
http://www.marslett.us/gentoo-distfiles/ \
ftp://distro.ibiblio.org/pub/linux/distributions/gentoo/ \
http:/ftp.gentoo.bg/ \
rsync://mirror.opteamax.de/gentoo/ \
http://gentoo.mirrors.hoobly.com/ \
http://distfiles.gentoo.org/"
|
If this is just another install. Put the final make.conf and /etc/portage tree in place, and do an "emerge @world". I usually have to do it twice, running the command "USE=-cups emerge @world" the first time because of conflicts.
Otherwise, now is a good time to enable or disable some USE flags (a few at a time). Run emerge -vpe world to list all currently installed packages and their enabled and disabled USE flags. Edit /etc/make.conf adding changes you need to make.
View USE flags in use and enable or disable some |
mybox ~ # emerge -vpe world (Portage displays the packages and their USE flags, as an example, let's disable fortran, and enable ipv6 and unicode) mybox ~ # echo 'USE="nptl nptlonly ipv6 -fortran unicode"' >> /etc/make.conf |
Recent versions of glibc use /etc/locale.gen to define locale settings.
Define locales |
mybox / # nano -w /etc/locale.gen mybox etc # locale-gen |
Last but not least, you may want to alter the CFLAGS variable in your /etc/make.conf to optimise the code to your specific needs. Please note that using a long list of flags is rarely needed and can even lead to a broken system. I specify the processor type (often "native") in the march option and -O2 -pipe.
You may also want to switch to ~x86 or ~amd64 with the ACCEPT_KEYWORDS variabe. You should only do this if you can deal with the odd broken ebuild or package. Of course, if you do not do this and do "emerge -DuN @world" every few weeks, you'll see the same thing. If you'd rather keep your system stable, don't touch it!
What make.conf might look like, finally |
# These settings are for my Latitude laptop (real work, that is).
CFLAGS="-O2 -march=native -pipe"
CXXFLAGS="${CFLAGS}"
LINGUAS="en_US en de zh_TW zh_CN"
MAKEOPTS="-j3"
EMERGE_DEFAULT_OPTS="--jobs=3"
# WARNING: Changing your CHOST is not something that should be done lightly.
# Please consult http://www.gentoo.org/doc/en/change-chost.xml before changing.
CHOST="x86_64-pc-linux-gnu"
# These are the USE flags that were used in addition to what is provided by the
# profile used for building.
USE="a52 aac acpi alsa avahi avcodec avformat \
bash-completion bluray branding -berkdb \
cairo cdda cddb cdr cups \
dbus dc1394 device-mapper dshow dts dvd dvdr \
emacs encode exif firefox flac \
gdu gif gnome gpm gstreamer gtk hal \
id3tag ieee1394 jack jpeg \
-kde lcms ldap libcaca libnotify libv4l libv4l2 lightning lua \
matroska mmx mng mp3 mp4 mpeg ncurses nsplugin ntfs-3g ogg opengl oss \
pam pango pdf png ppds policykit \
samba schroedinger sdl spell sqlite stream svg sse sse2 \
theora tiff truetype twolame udev unicode usb \
v4l v4l2 vlm vorbis waveout wifi win32codecs wingdi wma-fixed \
X x264 xml xulrunner xv xvid \
threads"
ACCEPT_LICENSE="*"
# This is for the ebuilds that I could not get to work, and I need.
# Think of it as Gentoo hacking.
PORTDIR_OVERLAY="/home/cmarslett/my-portage"
# ---[Overlay Settings]--- #
source /var/lib/layman/make.conf
SYNC="rsync://www.marslett.us/gentoo-portage"
GENTOO_MIRRORS="\
http://www.marslett.us/gentoo-distfiles/ \
ftp://distro.ibiblio.org/pub/linux/distributions/gentoo/ \
http://ftp.gentoo.bg/ \
rsync://mirror.opteamax.de/gentoo/ \
ftp://ftp.halifax.rwth-aachen.de/gentoo/ \
http://gentoo.mirrors.hoobly.com/ \
http://distfiles.gentoo.org/"
|
You might want to recompile your whole system twice to make full use of your latest configuration changes. It would take quite a long time to complete and yield minimal speed benefits. But recompiling is still a good idea from the standpoint of maintaining system consistency. See the Gentoo GCC Upgrading Guide for a discussion on the benefits of ensuring a consistently built system and world. You can also let your system rebuild itself gradually over time as new versions of packages are released.
Recompiling only the packages that have been updated or that are documented as affected by your new USE flags will take enough time. In either case you might have to remove packages that block your upgrade. Look for "[blocks B ]" in the output of emerge -vpuD --newuse world and use emerge -C to remove them.
If the block occurs right after adding or removing a USE flag, you may need to build one or another of the blocked packages with the new USE flag, then build the rest. You may even need to build a script to build the blocked packages in a manually specified order.
Update your packages |
(Please note, switching to ~x86 will cause many packages to be upgraded) mybox etc # emerge -vpDuN @world (Take a good look at the package list and their USE flags, remove blocking packages if any, and start the lengthy process) mybox etc # emerge -DuN @world (79 packages have been (re)compiled) (AND remerge libtool to avoid further potential problems) mybox etc # emerge -1 libtool (Update config files, make sure you do not let dispatch-conf update config files you have edited) mybox etc # dispatch-conf mybox etc # update-etc (If gcc has been updated, you should run gcc-config) mybox etc # gcc-config -l (and possibly select a new default version) mybox etc # gcc-config i686-pc-linux-gnu-4.5.2 (If perl has been updated, you should run the perl-cleaner script) mybox etc # perl-cleaner all (In case of a major upgrade of python, you should run the python-updater script) mybox etc # python-updater |
You have to have the Sun/Oracle JDK 6.29 for Linux installed or alternatively build with "USE=-java" which will, incidentally, keep the debug console from working. This is because some of the java code violates the Sun Java specs. And the 6.29 version of the spec will build something that works from the bad source code: other versions (or iced tea), don't do so well. Note that you may need to use "java-config -S" (and "java-config -L" to list the possibilities) in order to enable the 6.29 java compiler.
Install app-text/texlive-core (provides pdflatex for virtualbox) and run "texmf-update". Install makeself (2.1.5-r1 or newer). After both of these are installed, you will need to execute "source /etc/profile" to make them available to the "emerge virtualbox" and "emerge vboxgtk" commands.
Note that vboxgtk requires that you specify "**" as well as "amd64" or "x86" in the package.keywords directory/file before it will build (at least, that was my experience in early 2012). virtualbox-additions and virtualbox-modules only need to have the keyword "amd64" or "x86" set in the package.keywords directory/file.
The problem with the java code appears to be fixed in the 9999 version of virtualbox, but when I try to build it, I get errors building both the fr-FR and en-US versions of the User Manual. I suspect this is an issue resulting from the 9999 ebuild not being compatible with the 2011 version of pdflatex (that is, texlive).
To install a client OS into a virtual machine, execute the following two commands and whe you start up the virtual machine select all the configuration options you need. Note that you must be logged into an account that is a member of the vboxusers group.
Starting up a Virtual Box Session |
mybox ~ $ sudo modprobe vboxdrv mybox ~ $ VirtualBox |
Install "aqemu" with "USE=kvm" if you are using qemu-kvm, without if you are using plain qemu. Mixing the two will definitely keep the build from finishing.
QEMU_*_TARGETS should also not specify a ppc or mips platform (I get 3 very consistent build errors if I specify either of these).
So far I have been able to build the open source version of vmware player but not the workstation version. My user name and password are not working and the reset support on the vmware web site don't seem to work.
I even tried to set up an entirely new user name and password and that did not work either!