Gentoo x86 Chroot Setup Guide

1. X86 Chroot Howto

A chroot is a operation to change the root directory of the current process and the children spawned from it. In the simplest terms, it allows us to setup a completely separate install inside the one that you are already running.

Setting up your Chroot for a new install

The first thing that you need to do is create a directory for your chroot to reside.

Code Listing 1.1: Creation of a directory for your chroot to reside

Create a directory that has enough space for a second install. foo is our example
# mkdir /foo

The next step is to download a stage three tarball to the chroot and untar it.

Code Listing 1.2: Going to the Chroot mountpoint

Stage filename shown below is an example, actual filename may vary
# mv stage3-x86.tar.bz2 /foo
# cd /foo
# tar xvjpf stage3-x86.tar.bz2

To actually proceed with the install at this point, you need to mount a few directories from your live system to the chroot.

Warning: You might have to create some of the directories in your chroot to be able to mount them, as you'll get the mount point does not exist.

Code Listing 1.3: Directories needing to be mounted in your chroot

Mount the following directories to their appropriate area within your chroot.
# mount -t proc none /foo/proc
# mount -o bind /dev /foo/dev
# mount -o bind /usr/portage /foo/usr/portage
# mount -o bind /usr/src/linux /foo/usr/src/linux
# mount -o bind /lib/modules /foo/lib/modules
# mount -o bind /sys /foo/sys
# cp /etc/resolv.conf /foo/etc/resolv.conf
Finally, if you want one /tmp for both
# mount -o bind /tmp /foo/tmp

Note: You might want to create a simple bash script you can run before you chroot to the directories for the future. It makes it a easier task to run one script then having to remember what each mount you need to do.

As you will notice this is by no means a secure chroot but for what we need it doesn't need to be. With all that mounted you can actually go into your new setup.

Code Listing 1.4: Entering your Chroot

# chroot /foo /bin/bash

As you are now in your new chroot, you can start a standard install from Configuring Portage.

Running X apps inside your chroot

In order to be able to launch applications with a GUI from inside your chroot when your X session was started outside the chroot, there are a few extra steps you must follow.

First, you must be using /tmp from outside the chroot (see above). Second, since /dev/pts is a separate filesystem to /dev you will need to mount that as well.

Code Listing 1.5: Mounting /dev/pts

# mount -o bind /dev/pts /foo/dev/pts

You will also need to copy your ~/.xauth file to the home directory of your user in the chroot.

Code Listing 1.6: Copying .Xauthority

# cp /home/user/.Xauthority /foo/home/chroot_user/

Note: You will need to redo this everytime you restart X.

Finally, when you are inside your chroot, you need to set the DISPLAY environment variable.

Code Listing 1.7: Setting DISPLAY

# export DISPLAY=":0.0"

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.

Updated May 2, 2006

Summary: This guide will show you how to create chroots to assist in testing packages for stablization.

Joshua Jackson
Author

David Morgan
Author

Shyam Mani
Editor

Mark Loeser
Editor

Donate to support our development efforts.