Let me introduce my system first. I run an AMD Athlon Tbird at 1.1 GHz, two hard-drives on two different IDE controllers, both on the same main-board. My current system is all contained in and installed on one hard-drive, and my target is on another. I have some data that I wish to keep on the target device, so a full reinstall is not possible. I also want to keep this in a "flawless" manner: no service disruptions unless it is really necessary.

My current system is installed on /dev/hde3 with /home existing on /dev/hde6. My target /boot is on /dev/hda1 and the / is on /dev/hda3. To keep the disruptions to a minimum, /home will remain unchanged. I also have a separate partition at /mnt/build that contains the portage tree, temporary build files and the distfiles.

Since I call myself a "hacker" at core, I can't really do something like this without learning something from the experience. (No, my current system is not so damaged that I'm forced to reinstall.) So, I shall also try some "new" things that are best off on a clean slate.

The first of these will be JFS as a change from my normal choice of ext3.

I will also change my default optimizations from -O2 to -Os to see if I can reduce a problem I've had recently with large memory footprints.

I assume you are all familiar with the "normal" installation guide. If you have doubts about this, please take the time to read it again as I will try to avoid being redundant in this document.

First off, I'll wipe the partitions I'm going to install to. This is simple but a bit time-consuming:

# dd if=/dev/zero of=/dev/hda1 bs=512
dd: writing `/dev/hda1': No space left on device
48133+0 records in
48132+0 records out
# dd if=/dev/zero of=/dev/hda3 bs=512
dd: writing `/dev/hda3': No space left on device
6104701+0 records in
6104700+0 records out

Then I will initialize the partitions "as I want them". /boot on ext2. Stable. Classic. No frills.

# mkfs.ext2 /dev/hda1

I need the JFS tools on the host to build my target system.

# emerge sys-apps/jfsutils
# mkfs.jfs -L root_jfs /dev/hda3
mkfs.jfs version 1.1.2, 25-Mar-2003
Warning!  All data on device /dev/hda3 will be lost!

Continue? (Y/N) Y
   -

Format completed successfully.

3052350 kilobytes total disk space.

Now I am going to setup the basic premises for a Gentoo installation, mount the necessary devices, etc. At this point I had to rebuild my kernel with JFS filesystem support. This was done by simply checking JFS as a kernel module in the filesystems section, then make dep && make modules && make modules_install.

# mkdir /mnt/target
# mount /dev/hda3 /mnt/target
# mkdir /mnt/target/boot
# mount /dev/hda1 /mnt/target/boot
# df -h /mnt/target
# mkdir /mnt/target/mnt/build
# mount --bind /mnt/build /mnt/target/mnt/build
Filesystem            Size  Used Avail Use% Mounted on
/dev/hda3             2,9G  524K  2,9G   1% /mnt/target		

Now that we have the basic preparations done, we need a stage build. Since I want -Os instead of -O2 I will not use a stage3 build, which I would normally use. Instead I fetch the latest stage2 from http://www.ibiblio.org/gentoo/experimental/x86/stages/ to test them.

# cd /mnt/target && tar -xvjpf /root/stage2-x86-1.4_pre20030407.tar.b
z2
# mount -t proc proc /mnt/target/proc
# cp /etc/resolv.conf /mnt/target/etc/resolv.conf
# chroot /mnt/target /bin/bash
# env-update ;  source /etc/profile

Then I setup /etc/make.conf the way I want it. Here is my current list of USE flags:

apm avi encode libg++ libwww mikmod mpeg ncurses nls pdflib 
qtmt quicktime spell xml2 xv zlib gdbm berkdb slang readline 
aalib tcltk java guile X sdl gpm tcpd pam perl python esd imlib 
gtk motif mozilla gphoto2 ldap cdr crypt alsa  oggvorbis gnome 
gpg gpgme bonobo oss ssl xmms 3dnow mmx  opengl  tiff png jpeg 
smooth truetype gif ggi samba xv gtkhtml dvd -lirc -gtk2 -arts 
-qt -kde -cups -sse -tetex -doc -svga 

I also set the CHOST, CFLAGS and other variables that need to be altered.

I should point out that I have not done an emerge sync yet and will not do so. I will simply re-use my old configuration where the portage tree and build area are on a different partition. This data changes often and so deserves it's own partition.

PORTAGE_TMPDIR=/mnt/build
DISTDIR=/mnt/build/distfiles
PKGDIR=/mnt/build/packages
PORTDIR_OVERLAY=/usr/local/portage
GENTOO_MIRRORS="ftp://ftp.sunet.se/pub/Linux/distributions/gentoo/ http://gentoo
.oregonstate.edu/"
MAKEOPTS="-j1"

# cd /usr; rm -fr portage; ln -s /mnt/build/gentoo-x86 portage

And now it is time to emerge system and hope for the best.

# time  nice -n +15 emerge -u system
/bin/sh: line 1: gluUnProject._man: No space left on device
:79: I/O error on output
make[5]: *** [gluUnProject._man] Error 1
make[5]: Target `all' not remade because of errors.
make[5]: Leaving directory `/mnt/build/portage/xfree-4.2.1-r2/work/xc/doc/man/GLU'
...
...
real    90m11.657s
user    74m18.390s
sys     8m19.480s

Just great. After deleting some distfiles (the files in /mnt/build/distfiles) I freed about 1.2 Gb of space. At this point I regret not using ccache. Time to enable that :)

This goes in /etc/make.conf
FEATURES="sandbox ccache"
CCACHE_SIZE="1G"
This is in the (chrooted) shell again
# cat /etc/env.d/99ccache
CCACHE_DIR=/mnt/build/OLD/cache/

And after that disturbance it's back to compiling.

# time nice -n +15  emerge -u system
real    106m5.162s
user    71m40.320s
sys     10m41.320s

After this I setup the timezone and emerge the following packets:

# emerge sysklogd vanilla-sources jfsutils

Now comes the fun part. Since I have a working kernel running and configured correctly for my system I just copy the host's .config, issue a make oldconfig and then do a quick make menuconfig to check that I have all necessities.

# nice -n +15 make oldconfig dep bzImage modules

By this time, I have the same kernel built that I have for the host system, which is a good thing in case something does `uname -r` to check the system I'm building with. Of course, you could argue that such things are bad and should be removed, but sometimes it is justified.

After installing the kernel as normal, it's time to make sure I get the right modules built and installed. Checking the host system and installing them on the target is a good start.

# qpkg -v -f /lib/modules
media-libs/svgalib *
media-sound/alsa-driver *
media-video/nvidia-kernel *
sys-apps/i2c *
sys-apps/lm_sensors *
sys-apps/pcmcia-cs *
sys-kmods/lm_sensors *

A bit messy as you can see, but the general populace is i2c (requirement of lm_sensors), pcmcia-cs , alsa-driver and nvidia-kernel. Let's start with pcmcia-cs and nvidia-kernel since those are the most important ones for my system right now.

# nice -n +20 emerge -pv pcmcia-cs nvidia-kernel lm_sensors
# ALSA_CARDS="trident dummy" nice -n +15 emerge alsa-driver -pv

At this time I have not done any configuration at all, but I'd better do that soon. "Or else" :). I'll start by installing a usable editor and some miscellaneous console things that I feel I need. I will also install a mail-server and a cron daemon. (Mail-server first to satisfy the cron daemons need for a mail-server.)

# nice -n +15 emerge lftp vim screen postfix gnupg -v
# nice -n +15 emerge fcron 

Oops, I forgot the ntp daemon, wireless-tools and SpamAssassin:

# nice -n +20 emerge ntp wireless-tools Mail-SpamAssassin

In this chapter I'll do the basic configuration that I ignored previously. To avoid problems, I will start by enabling the services (so I won't forget it) and go on by configuring each service in it's own section after that.

# rc-update add sysklogd default
# rc-update add fcron default
# crontab /etc/crontab
# rc-update add alsasound boot
# rc-update add sshd default
# rc-update add lm_sensors default
# rc-update add pcmcia default
# rc-update add ntp default
# rc-update add net.eth0 default
# rc-update add spamd default

This concludes the services section; onwards to configuration.

I have a little special configuration for my syslogger; namely that I always wish to keep parts of my logs on two open terminals. Setting this up is generally quite simple unless you use Metalog, in which case you have to do extra hacks. See the Metalog documentation for that. Here is a partial diff -u against the original conf to my personalized settings.

-#cron.*                         /var/log/cron.log
+cron.*                         /var/log/cron.log
+*.emerg                                                 /dev/tty9
+*.info;kern.none;mail.none;authpriv.none;cron.none;     /dev/tty10
+kern.*                                                  /dev/tty11

Setting up alsa the first time can be a hassle. Therefore, I'm just migrating my own settings from the old, proven and working system onto my new partition. I'll post the config diff here for your dubious pleasure.

+alias snd-card-0 snd-trident
+alias sound-slot-0 snd-card-0
+
+alias snd-card-1 snd-dummy
+alias sound-slot-1 snd-card-1

Just don't forget to run alsamixer once you have rebooted. For my part I just copied /etc/asound.state onto the new partition, retaining all settings perfectly.

Unfortunately you cannot do this properly from inside a chroot since it depends on modules being loaded and what not. You will have to redo the configuration in your clean booted system at a later moment.

When I first did this in Gentoo it was something of a black art. I pulled the config from my then working LFS partition (that was adapted from RedHat). This config is still in my system, albeit a bit different now. So, I figure it is time to restart configuring it completely and see what can be done about it.

On my system eth0 is my internal network, on a normal NIC, and eth1 is my external network, on a PCMCIA wireless NIC.

First, I copy over /etc/init.d/net.eth0 script to /etc/init.d/net.eth1. Then I set need pcmcia in the net.eth1 script. I also modify net.eth0 to read before pcmcia instead of use pcmcia. This way I won't be stuck without a network internally if the pcmcia card is down or restarted.

The default /etc/conf.d/pcmcia was ok for me, which meant I have yet to fix /etc/conf.d/net and the pcmcia config.

Configuring pcmcia networking is pretty straightforward once you understand it. Open /etc/pcmcia/wireless.opts and set it up according to how the documentation inside that configuration explains. Don't forget adding it to the default runlevel.

# rc-update add net.eth1 default

Otherwise you may be without a network.

Setting up NTP is really quite simple. First I want to make sure that ntp actually syncs with servers continuously, not at boot. That means disabling ntpdate and using the normal service. Here is the resulting /etc/ntp.conf:

logfile         /var/log/ntpd.log
driftfile       /var/lib/misc/ntp.drift

server ntp1.sp.se prefer
server ntp1.sth.netnod.se
server ntp.lth.se
restrict default ignore
restrict 192.168.0.0 mask 255.255.255.0 notrust nomodify notrap

I also take a moment to edit /etc/init.d/ntpd so it has an after net.eth1 in it. This, together with setting NTPDATE_CMD="ntpd" in /etc/conf.d/ntpd, assures me that most of my timing issues will be gone.

Unless you wish to change how your SSH configuration works, you can simply copy /etc/ssh/ssh_config and /etc/ssh/sshd_config to your target system.

# cp -p /etc/ssh/*conf* /mnt/target/etc/ssh

Setting up module loading the way I want it requires some care. First, I have to make sure I have all the needed hardware support in my kernel (I know I do) and I also need to make the alias work nicely. First I create /etc/modules.d/usb and setup my camera (usb storage, generic).

alias /dev/sda1 sd_mod
pre-install sd_mod      modprobe -k usb-storage;sleep 5s
pre-install usb-storage modprobe -k usb-uhci

Second I setup /etc/modules.d/cdrw to automatically "just work" and clean up after it's done. I also make sure that ide-cd ignores the device that is my CDRW (if ide-cd is loaded for that device then burning won't work).

options ide-cd ignore=hdb
alias scd0 sr_mod
pre-install sg     modprobe -k ide-scsi
pre-install sr_mod modprobe -k ide-scsi
pre-install ide-scsi modprobe -k  ide-cd 

Then, a quick alias for my network to go into /etc/modules.d/net. Finish off by doing a modules-update.

alias eth0 8139too

# modules-update

fstab is well documented all around the net and in our normal installation instructions, so I'll just add a few notes about the differences to my settings and the default.

/dev/cdroms/cdrom0  /mnt/cdrom      iso9660    noauto,ro,users,unhide  0 0
/dev/sda1           /mnt/usb        vfat       noauto,defaults,users   0 0

The "users" allows users to mount and unmount; unhide will show even hidden files on the cdrom. /dev/sda1 is in my case a digital camera on usb-storage, as configured earlier in the modules section.

Another thing to setup is to have your "old" system mounted ( say on /mnt/old). This will allow for simple checks between the systems once you have your new system up and running.

The /etc/rc.conf probably doesn't need much mention here. Neither does grub configuration.

This chapter will deal with how to move other, non service related settings to your new system. This includes users, groups, host identifications and different settings that aren't related to the boot process of the system.

Now it is time to migrate the user and group data from your old system into the new one; files to watch out for are:

/etc/shadow
/etc/passwd
/etc/group
/etc/hosts.allow
/etc/hosts.deny

In this case, diff -u is a handy tool to check that you merged all groups and users. (No, don't just copy things over, doing that might mean that new users aren't merged properly between Gentoo versions).

Migrating SSH host settings is a fairly simple, yet important process. If not done, or done incorrectly, scripts and users who depend on your system will have problems from facing a man in the middle warning and connections may fail. Copy over the keys to your new system (make sure you get permissions right):

# cp -p /etc/ssh/ssh_host* /mnt/target/etc/ssh

The most important file is /etc/X11/XF86Config. In many cases it's okay to just copy it as-is into the new system. However, sometimes you may wish to only back it up and then generate a new config from scratch. Especially if you have been adding or removing font configurations or have entries for old hardware left.

# cp /etc/X11/XF86Config /mnt/target/etc/X11

Since nethack stores savegames and bones in the /usr/share/games/nethack directory, we need to copy these over into the target system. Since it's also runs as setuid games, we need to preserve permissions.

# emerge nethack
# cp -pr /usr/share/games/nethack/save /mnt/target/usr/share/games/nethack
# cp -p /usr/share/games/nethack/bone* /mnt/target/usr/share/games/nethack

Most systems require far more software than what has been covered here. For a normal desktop there is usually a myriad of small programs that are in use from time to time. You will miss many of those when scripts break or users complain. This chapter will go through some of the necessary parts of finding software which you may want to install on your target system.

There are a few useful tools for identifying commonly used programs. One is qpkg from the app-admin/gentoolkit package. Another is epm. For epm you do epm -qf /usr/bin/qpkg to find out what package "qpkg" belongs to. For qpkg the syntax is qpkg -f /usr/bin/qpkg.

But above this, there is the /var/cache/edb/world file where all explicitly installed packages are listed. This file will contain all packages you've ever installed explicitly through emerge. In my case it isn't desirable to install all the packages that are listed in the world file, instead I will use my judgement and only install parts of it.