Chroot

Resources

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's root directory. This new environment is known as a "chroot jail." A user operating inside the jail cannot 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. Chroot is often seen as a lightweight alternative to virtualization because it is able to run without the overhead of a hypervisor.

Prerequisites[edit | edit source]

Setting up the environment[edit | edit source]

When creating a new chroot setup, the first thing needed is a directory in which the chroot can reside. For example, a chroot could be created in /mnt/mychroot:

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

To mount an existing installation from a partition the following command can be run. Be sure to replace the <DEVICE> string in the example below with the drive and partition of the existing installation:

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

If an installation has been previously created in a sub directory of the current root file system, the above steps need not be repeated.

Unpacking system files and the Portage tree (new installations)[edit | edit source]

When building a new install, the next step is to download the stage3 tarball and unpack it to chroot location. For more information on this process please see Downloading the stage tarball and Unpacking the stage tarball in the Gentoo Handbook.

root #links http://distfiles.gentoo.org/releases/amd64/autobuilds/
root #tar xvjpf stage3-*.tar.bz2 -C /mnt/mychroot

Configuration[edit | edit source]

Before entering the chroot a number of directories must be mounted:

root #mount --rbind /dev /mnt/mychroot/dev
root #mount --make-rslave /mnt/mychroot/dev
root #mount -t proc /proc /mnt/mychroot/proc
root #mount --rbind /sys /mnt/mychroot/sys
root #mount --make-rslave /mnt/mychroot/sys
root #mount --rbind /tmp /mnt/mychroot/tmp

Some basic configuration files must be copied from the host. Do not copy /etc/portage/make.conf when using an existing installation:

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

Usage[edit | edit source]

Once done, enter the chroot environment by executing the following commands:

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

When creating a new installation, Portage should be synced to make sure everything is up to date.

(chroot) root #emerge-webrsync
(chroot) root #emerge --sync

The system is now ready. Feel free to install software, mess with settings, test experimental packages and configurations -- all without having any effect on the main system. To leave the chroot simply type exit or press Ctrl+d. Doing so will return the console to the normal environment. Do not forget to umount the directories that have been mounted.

systemd-nspawn[edit | edit source]

If the system uses systemd, systemd-nspawn can be used, which can automatically handle much of the boilerplate required in administering chroots. For example, to enter a chroot via systemd-nspawn with the same configuration as specified in the Configuration section, simply run:

user $cp /etc/portage/make.conf /mnt/mychroot/etc/portage
root #systemd-nspawn -D /mnt/mychroot --bind=/tmp --resolv-conf=/etc/resolv.conf

Init scripts[edit | edit source]

If setting up chroots is a task that must be performed often, it is possible to speed up the mounting of the directories by using an init script. The script could be added to the default runlevel and therefore set up automatically on system boot:

FILE /etc/init.d/mychroot
#!/sbin/openrc-run
 
depend() {
   need localmount
   need bootmisc
}
 
start() {
     ebegin "Mounting chroot directories"
     mount -o rbind /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"
}

When using a different directory or partition, add the necessary mounting commands in the start() function and change /mnt/chroot to the appropriate name.

See also[edit | edit source]

External resources[edit | edit source]

This article is issued from Gentoo. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.