Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc



This document provides advice and instruction regarding the installation of Gentoo onto a random RedHat Linux box, which is headless, remote, or otherwise inaccessible via console. Much, but not all, of the advice here might help if your objective is to install Gentoo onto a non-Gentoo, non-RedHat x86{,_64} Linux distribution with a "typical" array of user-land tools.

This guide notably does not assume that there is room on the hard drive's partition table for a new Gentoo installation (these days this is surprisingly easily overcome). In short, with careful planning and some luck, this guide will get Gentoo installed onto a Linux box which was designed to run some other distribution forever, and whose only input inlet is an ssh connection.

Words of Caution

As you read the following, bear in mind that the following may be out-of-date, misguided, or just a "thinko." If you absolutely cannot afford to lose contact with your box (i.e., your small space capsule's life support system) don't attempt this procedure! (Good luck solving your problem if this describes your situation. Your best bet is to go buy yourself a clone of the remote system's hardware and hack on that, or, better yet, rethink your approach to somehow tolerate a failure more gracefully).

Author "Rice" did this to a Fedora Core 2 Box. Many of these procedures will probably work for some other distribution, but some will not.

If you expect this to be easy, I don't think you have thought it through. This is an inherently complicated objective. It's like those games where you have to get various mutually antagonistic animals from one side of the river to the other in a boat. It seems simple enough until you try to write down the steps... I suggest you read this whole guide, at least, before you plow ahead with your conversion project. There are many irreversible steps and many ways to wedge your box to the point where you will need a human with a brain (not just a finger) to fix it.


This was ultimately inspired by HOWTO Replace RedHat with Gentoo, Remotely over SSH. At the time, I found the procedure there to be confusing, so I started pondering alternatives.

Then I found HOWTO - Install Debian Onto a Remote Linux System. That seemed more elegant, so this began as an attempt to approximate this latter approach for Gentoo.


The Basic Idea

  1. Pray. You want the gods on your side for this.
  2. Shrink your original installation until it is smaller than your swap partition.
  3. Turn your swap partition into a Linux partition.
  4. Clone your original installation onto the newly formatted partition.
  5. The scary part: Boot the clone.
  6. Wipe out your original installation... this will become Gentoo.
  7. Prepare the destination partition for Gentoo.
  8. Format and mount the new Gentoo partition.
  9. Follow the Gentoo install instructions (mostly).

The Procedure

Step Zero: Practice

Use a virtual machine or a spare computer running a clone of the remote install. Every time you render your test machine non-bootable, you will thank yourself for practicing! Create a concise, step-by-step guide to your procedure which you can follow mostly by cutting and pasting.

Step One: Create a Temporary Partition

To overcome init's death-grip on certain resources, you'll need a "temporary" partition (it may in fact be permanent) which will act as your "install cd." You could decide to install Gentoo there but this guide assumes you clone your existing system onto it.

This partition will need to be large enough to accommodate a clone of your existing system, and small enough to leave room for a Gentoo install (at least). So get rid of as much fancy functionality as you safely can... you'll have to use your judgment here to pick the right things.

If you only have a big single partition (i.e.: no swap or loop swap devices), or if you don't want to mess around with your partitions at all, your best bet is to use a "loop" device (see The Loopback Root Filesystem HOWTO for the details). Just pare down your current installation until it has enough free space to accommodate Gentoo, and don't forget to add the appropriate clauses to grub.conf when you hack on it below.

If you have lots of partitions then find some way to free one up (you are in a great situation here). For example you could make enough space for "/usr" on "/", and create a bind-mount to access the hidden file areas covered by the /usr mount, i.e.:

# mkdir /also
# mount -o bind / /also
# tar -cf /usr | ( cd /also/usr ; tar -xvpf - )

If you convince all processes to unlock /usr, you could simply unmount /usr here. This might be a hassle so comment out /usr in fstab, and reboot to get it unmounted (check your work carefully, a single typo will wedge your box).

The remainder of this guide assumes you are using a swap partition; adjust your procedure accordingly.

Unmount your swap paritition using swapoff [your swap partition, i.e.: /dev/hda2]. Edit /etc/fstab and comment out the line referring to that swap partition.

Reboot and check that the swap is not mounted any longer.

Now run fdisk [your drive, i.e.: /dev/hda], and change the type of that partition to "Linux" (83).

Edit /etc/fstab and remove the line referring to the swap partition (to prevent your system from attempting to mount the partition on reboot).

Step Two: Clone Your OS

This is the hardest step. The problem is no better or worse than that of making a backup of a running Linux system. When this was originally written, I suggested a pretty crude approach using dump/restore. This might still work if you happen to be running an ext2 or ext3 file system mounted on a physical partition but I don't recommend it.

Note that you may be able to skip this. Modern Red Hat systems create an LVM2 "logical volume" containing an ext3 filesystem. This will add to the complexity, but not the difficulty, of installing Gentoo on your system. To determine if your system is based on LVM, use the command:

# cat /proc/mounts | grep -v rootfs | grep ' / '

if you see something like:

/dev/mapper/bar-foo / ext3 rw 0 0

(note the "/dev/mapper" part), then your system is probably using LVM. If this is the case, you should probably do your upgrade using the features of LVM, not the hacks in this section. You want to create a new "logical volume" and install Gentoo on that. You may still need to do some sort of "cloning" to make this work, and gentoo will need an initramfs to boot. Read for ideas on how to use LVM, and read the official Gentoo LVM stuff as well as the various "Raid/LVM" guides in this wiki for ideas. A working initramfs is generated by the genkernel program. If you run it in "initrd" mode, it will build a Gentooish initramfs for the kernel at /usr/src/linux and install it to /boot without messing with your kernel at all. Just remember to add it to grub or your kernel will panic on boot.

One Way To Do It

A bleeding-edge "dar" will duplicate your fs to a very high (but not perfect) degree of fidelity -- much higher than "cp -a" is capable of. Dar is a backup program and pipe-unfriendly; if you are in a disk-space crunch, dar won't work. A good alternative is "star," which works more like tar than dar. If you are new to these tools, be prepared for a lot of reading & experimenting before you get the hang of them. These alternatives will work for all filesystems, not just ext2/3. When using dar for this purpose, I use syntax like:

dar -N -c /backup/location -y9 -ac -R /source

to make a backup of "/source" and

dar -N -x /backup/location -v -R /dest

to "restore" the backup to "/dest". Dar has a good man-page so read it.

Another Way

Another approach was suggested by an anonymous contributor in discussion (edited for readability):

This recipe sounds dangerous.

A safer alternative to cloning a live file system would be to install Gentoo into the swap partition the normal way (see below), boot this Gentoo as the temporary partition, and then install Gentoo once again, into the main partition, from there. The swap partition could then be converted back into swap.

Indeed, this will work. It adds an extra Gentoo install process to an already long list of steps, but it manages to avoid any possibility of a wedged box due to a faulty backup. If the system you are working on is important and getting a human to it would be difficult, you might want to consider this approach.

The Original Way

Warning: The following only works with ext2 or ext3 filesystems.

Run swapon -s and ensure that your swap partition is not Active. Now format the swap partition as you want it to be, i.e.: mkfs.ext3 /dev/hda2.

Code: clone "/"
mkdir /mnt/clone
mount -t [your partition type i.e.: ext3] [the newly formatted partition, i.e.: /dev/hda2] /mnt/clone
cd /mnt/clone
sync; sleep 5; sync; sleep 5; sync && \
dump -0 -f - / | restore -r -f -

answer any prompts here -- you do NOT want to abort so the answer would probably be "no"

rm restoresymtable

Be advised that this is not a perfectly safe operation. You are cloning a filesystem from raw data while it is live, so don't be surprised if you got some scary warnings. However, this should get any "magic" parts of your filesystem cloned for you. To be sure that the rest of your data is cloned, including anything you might mount on separate partitions, you could follow this by using the "cp" command to re-copy most things again. You will have to use your judgement about what, if anything, to copy. Perhaps something like:

Code: use cp to clone "/" again
cd /mnt/clone
unalias cp
cp -av /bin /etc /home /lib /root /sbin /usr /var .

Step Three: Boot Into the Clone

Edit /mnt/clone/etc/fstab and change the root partition to point to its new home (i.e., you might change Label=/ to /dev/hda2. This way everything will be consistent.

Warning: These directions will assume you are running Fedora's grub, and that you have a separate "boot" partition mounted at /boot. If that is not the case, then you will probably need to adjust for this! In particular, if you are using lilo, you will need to use a significantly different approach (see the "-R" argument to lilo for a start).

Next edit /boot/grub/grub.conf. You want to add a clone of the entry that boots. Remember that grub starts counting at zero, so if it says default=1, then the second entry will boot! Add your clone just after the currently active entry. Change the root= option in your cloned entry to refer to the temporary "clone" partition (i.e., to root=/dev/hda2. This might look like:

Code: /boot/grub/grub.conf
title Fedora Core (2.6.10-1.771_FC2)
        root (hd0,0)
        kernel /vmlinuz-2.6.10-1.771_FC2 ro root=LABEL=/ selinux=0
        initrd /initrd-2.6.10-1.771_FC2.img
title FC2 Clone (2.6.10-1.771_FC2)
        root (hd0,0)
        kernel /vmlinuz-2.6.10-1.771_FC2 ro root=/dev/hda2 selinux=0 panic=30
        initrd /initrd-2.6.10-1.771_FC2.img

Note the panic=30 which tells the kernel to reboot if, for some reason (i.e.: there was no /sbin/init where you told it to look), there is a kernel panic. For reasons explained below, it will reboot back into the original system in this case. Also, note that I did not set the clone as the default yet.

Now we can use a Fedora innovation. Many grubs, perhaps including Gentoo's, lack this feature, which is too bad because it is a useful one.

Code: Fedora Grub trick
linux# grub
grub> savedefault --default=[number of the new entry you created, i.e.: 1] --once
grub> quit

This will cause grub to boot your new partition once and only once, and revert afterwards to the default stored in grub.conf. That way, even if things get completely stuck (i.e.: your machine boots into linux, but there is no networking (a problem which can be avoided: see below)), in the worst case, a power-cycle would be required. Very good for kernel upgrades. In fact, if you are running Fedora, I suggest you don't install the Gentoo grub but continue to use Fedora's -- that way you can keep this useful feature for future kernel upgrades.

Now reboot! If and when your server comes back (!) you will hopefully have what was your swap partition mounted as root. Just use mount to check. If everything looks OK, edit grub.conf to make your new entry the default.

Time to celebrate, you finished the insufferably time-consuming first part of the procedure and have made it to the even more insufferably time-consuming second part!!!

Step Four: Install Gentoo

Make a /mnt/gentoo directory and mount your new root there. Change /etc/fstab to reflect the new arrangement, and copy it to /mnt/gentoo/etc, adding any gentoo-specific stuff from the handbook and nixing any RedHat-isms.

You are now ready to follow the Gentoo Handbook install instructions, starting with "Creating Filesystems," and ending at "Installing Necessary System Tools". Of course, as you follow the Gentoo Handbook instructions, you will probably want to skip the parts about partitioning and installing a boot-loader, since you already did them.

Before you reboot, remember these important extra steps:

You may wish to keep Fedora (or whatever it is) around. First, if you don't own the hardware, whoever put the old OS on might like it to still be there; second, you can use it as a maintenance partition yourself. On the other hand, you may wish to just be rid of it, in which case be my guest and just make it back into a swap partition.

However, if you are keeping it, where will your swap go? Ideally you would repartition, but that is scary. If you'd rather play it safe, create a loopback file for your swap, i.e., for a 1g swap (untested):

# dd if=/dev/zero of=/LOOP_swap bs=1M count=1024
# losetup /dev/loop/5 /LOOP_swap
# mkswap /dev/loop/5
# echo '# from Remote Install HOWTO' >> /etc/fstab 
# echo '/dev/loop/5 none swap sw,noauto 0 0' >> /etc/fstab
# echo '# The next two lines came from the Remote Install HOWTO' >> /etc/conf.d/local.start
# echo 'losetup /dev/loop/5 /LOOP_swap > /dev/null' >> /etc/conf.d/local.start
# echo 'swapon -a > /dev/null' >> /etc/conf.d/local.start
# echo '# The next two lines came from the Remote Install HOWTO' >> /etc/conf.d/local.stop
# echo 'swapoff /dev/loop/5 2>&1 > /dev/null' >> /etc/conf.d/local.stop
# echo 'losetup -d /dev/loop/5 2>&1 > /dev/null' >> /etc/conf.d/local.stop

Format the new system to your liking, blowing away the old files.

Once it boots, you win. Knock out the cron job and put Gentoo as the default in grub.conf.

You now have a Gentoo system, enjoy!


Concerns or Compliments? Please use the Discussion section.

Retrieved from ""

Last modified: Tue, 12 Feb 2008 14:00:00 +0000 Hits: 16,477