Project:X86/Chroot Guide
This guide provides instructions on how to create a fresh Gentoo installation inside a chroot to assist in testing Gentoo packages for stabilization and for other sundry testing.
A chroot is an operation to change the root directory of the current process and the children spawned from it. In this new root a completely separate operating system can be installed inside the one that is already running, with some limitations.
This is by no means a secure chroot, this guide should only be used for testing purposes.
Setting up a directory for the 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.
root #mkdir /fooThe 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:
user $mv stage3-amd64-openrc-20240915T163400Z.tar.xz /foo
user $cd /foo
user $tar xpvf stage3-*.tar.xz --xattrs-include='*.*' --numeric-owner
Setting up required mount points
To proceed with the install it is necessary to mount a few directories from the live system to the chroot.
The sys-apps/arch-chroot package may help replace all these mount commands, which should simply require:
user $cp --dereference /etc/resolv.conf /foo/etc/resolv.conf
user $emerge sys-apps/arch-chrootuser $arch-chroot /fooSome 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:
root #mount -t proc none /foo/proc
root #mount -o bind /dev /foo/dev
root #mount -o bind /usr/portage /foo/usr/portage
root #mount -o bind /usr/src/linux /foo/usr/src/linux
root #mount -o bind /lib/modules /foo/lib/modules
root #mount -o bind /sys /foo/sysRemember to copy over DNS info so that the chroot can access the Internet properly:
root #cp --dereference /etc/resolv.conf /foo/etc/resolv.confFinally, if sharing a /tmp directory between both systems is required:
root #mount -o bind /tmp /foo/tmpIt 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.
Enter the chroot
With all of the filesystems mounted, proceed into the new setup. Enter the Chroot:
user $chroot /foo /bin/bashHurray! 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 /dev/pts:
root #mount -o bind /dev/pts /foo/dev/ptsThe the ~/.xauth file will need to be copied to the home directory of the user in the chroot environment:
user $cp /home/user/.Xauthority /foo/home/chroot_user/
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.
user $export DISPLAY=":0.0"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.