From Gentoo Wiki
Jump to: navigation, search
Other languages:
English • ‎español • ‎français • ‎日本語 • ‎한국어 • ‎русский • ‎Türkçe • ‎中文(中国大陆)‎

Chroot (Change Root) is a Unix system utility used to change the apparent root directory to create a new environment logically separate from the main system. This new environment is known as a "chroot jail". A user operating inside the jail can not see or access files outside of the environment they have been locked into.

One of the main uses for chrooting is to create a separate Linux system on top of a the current one for the purpose of testing or software compatibility. It is often seen as a lightweight alternative to virtualization because it is able to run without the overhead of a hypervisor.

Setting up the environment

The first thing that you need to do when you create a new installation is create a directory for your chroot to reside in, for example in /mnt/mychroot:

user $mkdir /mnt/mychroot
user $cd /mnt/mychroot

If you want to mount an existing installation from a partition, you can do:

user $mkdir /mnt/mychroot
user $mount /dev/DEVICE /mnt/mychroot

Replace DEVICE by the partition with your existing installation.

If you already have an installation in a sub directory of the root you are currently in, you don't need to do the above steps.

Unpacking system files & portage tree for a new installation

If you're building a new install, the next step is to download the stage3 and portage tarballs and set them up in the chroot location. For more information on this process please see sections 5a and 5b in the Gentoo Handbook.

root #tar xvjpf stage3-*.tar.bz2 -C /mnt/mychroot
root #tar xvjf portage-*.tar.bz2 -C /mnt/mychroot/usr


Before entering the chroot we need to mount a number of directories.

root #mount -o bind /dev /mnt/mychroot/dev
root #mount -t proc none /mnt/mychroot/proc
root #mount -o bind /sys /mnt/mychroot/sys
root #mount -o bind /tmp /mnt/mychroot/tmp

And will also need to copy over some basic configuration file from the host, do not copy over make.conf if you're using an existing installation.

user $cp /etc/portage/make.conf /mnt/mychroot/etc/portage # If you use an existing installation, skip this command.
user $cp /etc/resolv.conf /mnt/mychroot/etc

Once done we can then enter the chroot environment.

root #chroot /mnt/mychroot /bin/bash
root #env-update
root #source /etc/profile
root #export PS1="(chroot) $PS1"

When creating a new installation, you can sync portage to make sure everything is up to date.

root #emerge --sync

The system is now ready. You can install software, mess with settings, test experimental packages and configurations without having any effect on your main system. To leave the chroot simply type "exit" or press Ctrl + D, this will return you back to your normal environment. Don't forget to umount directories you've mounted.

Init scripts

If you need to do this often, you can speed up the mounting of the directories needed for a chroot by using an init script:

FILE /etc/init.d/mychroot
depend() {
   need localmount
   need bootmisc
start() {
     ebegin "Mounting chroot directories"
     mount -o bind /dev /mnt/mychroot/dev > /dev/null &
     mount -t proc none /mnt/mychroot/proc > /dev/null &
     mount -o bind /sys /mnt/mychroot/sys > /dev/null &
     mount -o bind /tmp /mnt/mychroot/tmp > /dev/null &
     eend $? "An error occurred while mounting chroot directories"
stop() {
     ebegin "Unmounting chroot directories"
     umount -f /mnt/mychroot/dev > /dev/null &
     umount -f /mnt/mychroot/proc > /dev/null &
     umount -f /mnt/mychroot/sys > /dev/null &
     umount -f /mnt/mychroot/tmp > /dev/null &
     eend $? "An error occurred while unmounting chroot directories"

If you use a different directory or partition, add the necessary mounting commands in start() and change /mnt/chroot if you use a different name.

See also