This guide provides instructions on how to create chroots to assist in testing packages for stabilization.
What is a chroot?
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 one to setup a completely separate operating system installation inside the one that is already running.
Setting up a chroot for a new install
First create a directory for the chroot to reside; the filesystem that contains this directory must have enough space for a second Gentoo installation.
The next step is to download a stage three tarball to the chroot and untar it. The stage file name shown below is an example, actual file name may vary:
mv stage3-x86.tar.bz2 /foo
tar xvjpf stage3-x86.tar.bz2
To proceed with the install it is necessary to mount a few directories from the live system to the chroot.
Some of the directories in the chroot may not exist. They may need to be created to be able to mount at these locations. When this is the case the mount command will spit out a 'mount point does not exist' error. Simply run mkdir to create the mount points.
Mount the following directories to their appropriate area within the 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 to share a /tmp directory between both systems:
mount -o bind /tmp /foo/tmp
It is prudent to create a simple bash script that can generate the previous list of command. It makes it a easier task to run one script then having to remember to mount each directory. It will also save a lot of time.
This is by no means a secure chroot but for what is accomplished in this guide a secure chroot is not needed. With all of the filesystems mounted, proceed into the new setup. Enter the Chroot:
chroot /foo /bin/bash
Hurray! The chroot has been entered! Continue by starting a standard install from Configuring Portage.
Running X apps inside the chroot
In order to be able to launch applications with a GUI from inside the chroot when the X session was started outside the chroot, there are a few extra steps to be followed.
First, use the /tmp directory from outside the chroot (see above). Second, since /dev/pts is a separate filesystem to /dev, it will need to be mounted as well.
mount -o bind /dev/pts /foo/dev/pts
The the ~/.xauth file will need to be copied to the home directory of the user in the chroot environment:
cp /home/user/.Xauthority /foo/home/chroot_user/
cp /home/user/.xauth* /foo/home/chroot_user/
The above stop will need to be re-preformed every time X is restarted. Every time X is restarted the a new .Xauthority file is created.
Finally, when inside the chroot, set the DISPLAY environment variable.
This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Joshua Jackson, David Morgan, Shyam Mani, Mark Loeser
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.