| English | 日本語 |

Tokyo Linux Users Group

Author: Josh Glover

Introduction

This guide demonstrates how to install the Gentoo Linux distribution in a chroot jail. This can be done on a Gentoo system (obviously) or even an entirely different distribution, such as Red Hat Linux! This guide has been tested on RHEL3, but should work on at least Fedora Core releases, and probably Red Hat Linux 7.x, 8.0, and 9.0. It should also work on any modern Linux distribution, such as Debian (and by extension, Ubuntu and KNOPPIX), Mandriva, SuSE, and so on. Please add your success stories to the talk page for this article, and I will be happy to add them to this guide.

Why Would Anyone Do This?

You may be wondering exactly why anyone in his or her right mind would want to run one distribution inside another. The easy answer to this question is that I am not exactly in my right mind. The actual answer is a little more complicated, but here are some common reasons:

Directories

This guide assumes that you want to install Gentoo into a directory called faketoo in your home directory. If you want to install it elsewhere, that is fine, but you will need to watch out for occurrences of faketoo in this guide and change them to reflect your directory choice.

Free Space Requirements

Before you can install Gentoo into a jail, you should verify that you have enough space. The core system install requires just about 1GB of space. Of course, if you are planning to install hefty software packages like X, OpenOffice.org, Firefox, or a full LAMP stack, you will need to allow more free space. As a guide, here are some recommendations based on the feedback of people who have followed these steps:

Obtaining Gentoo Installation Media

You will need, at the very least, a Gentoo stage3 tarball. You probably also want a Portage snapshot tarball. Both of these wonderful things can be located on your favourite Gentoo mirror:

Save these files into your home directory, like so:

# Edit lines highlighted in red to match your setup

# If you are installing Gentoo into a chroot jail on a Gentoo host, comment out
# the next line (by adding a '#' character to the beginning of the line) and
# uncomment the line after it
#GENTOO_ON_GENTOO=0
GENTOO_ON_GENTOO=1


GENTOO_MIRROR=ftp://ftp.ecc.u-tokyo.ac.jp/GENTOO

# Normally, if you are installing into a jail on Gentoo, you will want to use
# a GENTOO_CPU and GENTOO_ARCH that match your real installation. The next bit
# of code attempts to detect this. If you think you know better, comment out the
# next line (by adding a '#' character to the beginning of the line) and set
# GENTOO_CPU and GENTOO_ARCH manually
GENTOO_ARCH_AUTODETECT=1

GENTOO_CPU=pentium4
GENTOO_ARCH=x86


# Only change this line if you changed GENTOO_ARCH to something besides x86
GENTOO_STAGE_PATH=releases/${GENTOO_ARCH}/current/stages/${GENTOO_CPU}

if test ${GENTOO_ARCH_AUTODETECT} -ne 0; then
    GENTOO_CPU=`sed -n -e 's/^.\+-march=$[^ ]\+$.\+$/\1/p' /etc/make.conf`
    GENTOO_ARCH=x86
    GENTOO_STAGE_PATH=releases/${GENTOO_ARCH}/current/stages/${GENTOO_CPU}

    chost=`sed -n -e 's/^CHOST="$[^\-]\+$-.\+$/\1/p' /etc/make.conf`
    case ${chost} in
        alpha )
            GENTOO_ARCH=alpha
            GENTOO_STAGE_PATH=releases/${GENTOO_ARCH}/current/stages
            ;;
        i386 | i486 | i586 )
            GENTOO_ARCH=x86
            GENTOO_CPU=x86
            ;;
        i686 )
            case ${GENTOO_CPU} in
               pentium3 | pentium4 | pentium-m | athlon-xp )
                    # No change to GENTOO_CPU necessary
                    ;;
               prescott )
                    GENTOO_CPU=pentium4
                    ;;
                * )
                    GENTOO_CPU=i686
                    ;;
            esac
            ;;
        hppa1.1 | hppa2.0 )
            GENTOO_ARCH=hppa
            GENTOO_STAGE_PATH=releases/${GENTOO_ARCH}/current/stages
            ;;
        powerpc )
            GENTOO_ARCH=ppc
            GENTOO_STAGE_PATH=releases/${GENTOO_ARCH}/current/stages
            ;;
        x86_64 )
            GENTOO_ARCH=amd64
            GENTOO_STAGE_PATH=releases/${GENTOO_ARCH}/current/stages
            ;;
    esac
fi

wget --passive-ftp ${GENTOO_MIRROR}/${GENTOO_STAGE_PATH}/stage3-${GENTOO_CPU}-\*.tar.bz2
wget --passive-ftp ${GENTOO_MIRROR}/snapshots/portage-latest.tar.bz2

Creating the chroot Jail and Installing Gentoo into It

Before we can install Gentoo into a chroot jail, we must create the jail. Which is a simple as:

# Edit lines highlighted in red to match your setup
FAKETOO_JAIL=${HOME}/faketoo

mkdir ${FAKETOO_JAIL}

Now, populate the jail with the stage3 tarball:

# Edit lines highlighted in red to match your setup
GENTOO_SOURCES=${HOME}

cd ${FAKETOO_JAIL}

# See the text below if you do not know what sudo does
sudo -v

bunzip2 -c ${GENTOO_SOURCES}/stage3-${GENTOO_CPU}-*.tar.bz2 | \
 sudo tar xvp

You may have noticed that there was some mention of sudo above; if this puzzles you, see the #sudo Explained section below.

You now have the Gentoo core system installed. In order to use Gentoo's excellent Portage tree, you will need to extract the Portage snapshot tarball into the jail. Of course, if you are installing onto a Gentoo system, you have the option of using the host system's Portage tree, in which case you should skip this step, but pay close attention to the next step, as you will need to bind mount the Portage tree in addition to the other mounts.

# Edit lines highlighted in red to match your setup

# If you want to use the host system's Portage tree, comment out the next line
# (by adding a '#' character to the beginning of the line), and uncomment the
# one following it
FAKETOO_INSTALL_PORTAGE=1
#FAKETOO_INSTALL_PORTAGE=0


if test ${FAKETOO_INSTALL_PORTAGE} -ne 0; then
    cd ${FAKETOO_JAIL}
    bunzip2 -c ${GENTOO_SOURCES}/portage-latest.tar.bz2 | \
     sudo tar xv -C usr/
else
    sudo mkdir -p usr/portage var/tmp/portage
fi

Mounting /dev and /proc

Gentoo is all installed inside the jail, but before you can use it like a real system, you must mount /dev and /proc inside the jail so that programs running in the jail have kernel-level access to your hardware.

Note that this is not what you normally want with a chroot jail, which is supposed to help mitigate a daemon being compromised! In our setup, however, we want to run Gentoo as if it was running directly on the real root filesystem.

Here is how to mount /dev and /proc (and, while we're at it, /usr/src, so that Gentoo can get at our kernel sources (which is required by some packages, like net-wireless/wireless-tools). Also, if you want to use the host system's Portage tree, we will need to mount two additional directories.

sudo -v
sudo mount -o bind /dev ${FAKETOO_JAIL}/dev
sudo mount -t proc none ${FAKETOO_JAIL}/proc
sudo mount -o bind /usr/src ${FAKETOO_JAIL}/usr/src
if test ${FAKETOO_INSTALL_PORTAGE} -eq 0; then
    sudo mount -o bind /usr/portage ${FAKETOO_JAIL}/usr/portage
    sudo mount -o bind /var/tmp/portage ${FAKETOO_JAIL}/var/tmp/portage
fi

Entering the Jail for the First Time

We are nearing the end, my friends! Before you enter the Gentoo jail for the very first time, you will need to copy your DNS resolver configuration over, and create one file that seems to be missing from Gentoo's baselayout. And if you have chosen to use the host system's Portage tree in a previous step, you will want to copy the host system's main Portage configuration file in to use as a starting point:

sudo -v
sudo cp /etc/resolv.conf ${FAKETOO_JAIL}/etc/resolv.conf
echo 'default' >/tmp/softlevel
sudo mv /tmp/softlevel ${FAKETOO_JAIL}/var/lib/init.d/softlevel
if test ${FAKETOO_INSTALL_PORTAGE} -eq 0; then
    sudo cp /etc/make.conf ${FAKETOO_JAIL}/etc/make.conf
fi

Now, you can enter the jail and start using your new, fake Gentoo system!

sudo -v
sudo chroot ${FAKETOO_JAIL} /bin/su - root
env-update
source /etc/profile
export PS1=': \u@FAKETOO; '
export PS2=': ; '

These steps will deposit you into your jail as the root user. You can now continue the normal Gentoo installation process by configuring Portage.

Please note that if you have installed your chrooted Gentoo on a Gentoo host system and have elected to use the host system's Portage, you probably want diverge from the instructions in the following ways:

Starting and Stopping Faketoo

Everytime you shut your computer down, you should first stop Faketoo. And after booting up, you must start Faketoo again before you can use it. The easiest way to accomplish this is by creating two scripts in your bin directory:

# Edit lines highlighted in red to match your setup

BINDIR=${HOME}/bin
FAKETOO_CRON=vixie-cron


cat >${BINDIR}/faketoo-start <<EOF
FAKETOO_JAIL=${FAKETOO_JAIL}
FAKETOO_CRON=${FAKETOO_CRON}
FAKETOO_INSTALL_PORTAGE=${FAKETOO_INSTALL_PORTAGE}

sudo -v
sudo cp /etc/resolv.conf \${FAKETOO_JAIL}/etc/resolv.conf
sudo mount -o bind /dev \${FAKETOO_JAIL}/dev
sudo mount -t proc none \${FAKETOO_JAIL}/proc
sudo mount -o bind /usr/src \${FAKETOO_JAIL}/usr/src

if test \${FAKETOO_INSTALL_PORTAGE} -eq 0; then
    sudo mount -o bind /usr/portage ${FAKETOO_JAIL}/usr/portage
    sudo mount -o bind /var/tmp/portage ${FAKETOO_JAIL}/var/tmp/portage
fi

sudo chroot \${FAKETOO_JAIL} /bin/su - root -c /etc/init.d/\${FAKETOO_CRON} start
EOF

cat >${BINDIR}/faketoo-stop <<EOF
sudo chroot \${FAKETOO_JAIL} /bin/su - root -c /etc/init.d/\${FAKETOO_CRON} stop
EOF

chmod +x ${BINDIR}/faketoo-*

Entering the Jail Normally

Once you have your chrooted system fully installed, you will probably want to add a non-root user for daily use, and enter the jail as that user. Easy as pie:

# Edit lines highlighted in red to match your setup

FAKETOO_USER=${USER}

sudo -v
sudo chroot ${FAKETOO_JAIL} /bin/su - ${FAKETOO_USER}

These steps will deposit you into your jail as the root user. You can now continue the normal Gentoo installation process by configuring Portage.

sudo Explained

sudo is a wrapper that lets you run a single command with superuser--root--privileges. When you ran

sudo -v

in the #Creating the chroot Jail and Installing Gentoo into It section above, you were asking sudo for a token, which allows you to commands as root for a few minutes, without being prompted for a password every time. The password that

sudo -v

expects you to enter is almost certainly your own, but if that doesn't work, try your system's root password (some distributions may setup sudo incorrectly).

Gentoo