Chroot

This material is work-in-progress ...

Do not follow instructions here until this notice is removed.
(Last edited by Dubiousjim on 20 Jan 2015.)

"Changing root" or "chrooting" is a method for zooming in on part of your filesystem, so that, for example, /path will refer to what was formerly accessible at /mnt/path. The "root" in the expression "chroot" refers to the root filesystem /, not to the root user. (Though typically you will need root user privileges in order to chroot.)

A common reason for chrooting is to perform maintenance on existing systems where booting and/or logging in no longer works. One has to boot the hardware somehow, such as with an Installation or Rescue CD or USB; then one mounts the broken system and chroots into it and performs the repairs. Common examples are:

reinstalling the bootloader
rebuilding the initramfs image
upgrading or downgrading packages
resetting a forgotten password

Chrooting can also be used to create and host a separate virtualized installation of a system. This can be useful for:

Testing and development, with software that's too risky to deploy on a production system.
Software can be developed, built and tested in a chroot populated only with its expected dependencies.
Can run legacy software or other software whose supporting libraries or data files can't be installed in the host system.
Open file descriptors (for files, pipelines and network connections) can be "carried into" the chroot by running programs, making it unnecessary for those programs' working files to be visible inside the chroot directory. This can help separate privileges or design sandboxes. Note that chroot is not a secure way to contain a hostile process with root privileges. See Wikipedia's discussion of some of chroot's limits.

Here are some other resources:

Preparation

All the steps in this guide will have to be performed as root user.
If you are using chroot to repair an existing Linux system, it will need to be mounted first. If you don't know the location and/or filetype of the disk(s) where it resides, read the output of fdisk -l or lsblk. We will suppose the broken system is at /dev/sdx1 and its filetype is ext3. Create a directory for mounting this disk, and mount it:
mkdir -p $CHROOT
mount -t ext3 /dev/sdx1 $CHROOT

where $CHROOT evaluates to the path you want to chroot into (for example, /mnt).
If the system directory is encrypted or in a LVM group or anything like that, we'll leave it to you to figure out what steps to take to prepare it and mount it.
If there are separate filesystems for other directories (such as /boot, /var, /usr, /home), mount them too:
mount /dev/sdx2 $CHROOT/boot
mount /dev/sdx3 $CHROOT/var
mount /dev/sdx4 $CHROOT/usr

For many repair tasks, you may not need to mount the broken system's /home directory.
If you do have /boot on a separate partition, it's essential to have it mounted before working with GRUB, performing a kernel upgrade, or anything of that sort. It's also possible to mount some of these filesystems after you've chrooted, and in some cases mounting /boot in particular after chrooting has worked better with GRUB. If you can, though, it's smarter to mount these beforehand. The reason is that if you do it from inside the chroot, the outside/host environment won't know about the mounted filesystems, so if you forget to umount them before exiting the chroot, the system won't know to umount them when it shuts down, either. That could damage those filesystems.
The script presented below will take care of generating or remounting other system directories like /dev, /proc, /sys, /tmp and so on.
The architecture of the host system you're booted into (e.g., if it's a 32bit LiveCD, that's x86) and the system you want to chroot into must match. You can determine what architecture you're booted into using uname -m.
Before chrooting, be sure any kernel modules you'll need when working inside the chroot have been loaded. For example:
modprobe dm-mod
modprobe dm-crypt
Set up your network if you'll need it inside the chroot, e.g., to install updated packages. The script presented below will copy the /etc/resolv.conf from the host system, but will prompt before overwriting an existing etc/resolv.conf inside the chroot. If you like, you can generate one from scratch by doing:
echo 'nameserver 8.8.8.8' > $CHROOT/etc/resolv.conf
If your host system is Alpine or another distribution (like Hardened Gentoo) that uses the grsecurity kernel patches, for some maintenance tasks you'll want to make sure some of the grescurity prohibitions are disabled. For example:
sysctl -w kernel.grsecurity.chroot_deny_chmod=0 # enable suid/sgid
sysctl -w kernel.grsecurity.chroot_deny_mknod=0
sysctl -w kernel.grsecurity.chroot_deny_mount=0
sysctl -p

For more info, see:
- http://en.wikibooks.org/wiki/Grsecurity
- http://www.gentoo.org/proj/en/hardened/grsecurity.xml

Performing the chroot

The most reliable way to chroot is to use the following script:

Contents of /root/start-chroot

#!/bin/sh -e
user=`whoami`
if [ "$user" != "root" ]; then
  echo "This script needs root access" >&2
  exit 1
fi
if ! [ -d "$1" ]; then
  echo "Usage: $0 <chroot directory>" >&2
  exit 1
fi
if [ x1 = x`sysctl -ne kernel.grsecurity.chroot_deny_chmod` ]; then
  echo "Warning: can't suid/sgid inside chroot" >&2
fi
if [ x1 = x`sysctl -ne kernel.grsecurity.chroot_deny_chroot` ]; then
  echo "Warning: can't chroot inside chroot" >&2
fi
if [ x1 = x`sysctl -ne kernel.grsecurity.chroot_deny_mknod` ]; then
  echo "Warning: can't mknod inside chroot" >&2
fi
if [ x1 = x`sysctl -ne kernel.grsecurity.chroot_deny_mount` ]; then
  echo "Warning: can't mount inside chroot" >&2
fi
cd "$1"
shift
cp -L /etc/resolv.conf ./etc/ || true
mount -t proc proc ./proc
mount -t sysfs sys ./sys
mount -o bind /dev ./dev
# next line is said to be important for pacman's signature check
mount -o bind /dev/pts ./dev/pts
case $1 in
  -l) shift;;
  -l*) one=${1#-l}; shift; set -- -$one "$@";;
esac
chroot . /bin/sh -l "$@"
umount ./dev/pts
umount ./dev ./sys ./proc

Copy that script to some location on your system, such as /root/start-chroot, run chmod +x on it, and then invoke it as:

/root/start-chroot $CHROOT

, where $CHROOT evaluates to the path you want to chroot into (for example, /mnt).

Comment on Environment variables, extra arguments to start-chroot.

It is certainly possible to perform a chroot by hand, without using this script. For some purposes, you can get away with a simpler procedure than the script follows. But it's hard to catalogue in advance when taking shortcuts will get you in trouble, so it's best to just get in the habit of using this script (or doing the same things it does). As you read around in various wikis (perhaps including this one), you will encounter a variety of instructions for how to chroot by hand. These instructions often differ in small details from each other and are usually not as thorough as the above script.

Inside the chroot

Now that you're inside the chroot, you can perform whatever troubleshooting you need to do:

resintall GRUB to your disk's MBR
reset a forgotten password
perform a kernel upgrade (or downgrade)
rebuild your initramdisk
fix your /etc/fstab
reinstall packages using your package manager
whatever

If you have multiple terminals open on or connected to the running system, the chroot will only be effective in the terminal that you performed it in.

Preparation

Performing the chroot

Inside the chroot

Cleaning up